typesea 0.1.0 → 0.2.0

package/dist/builders/object/guard.js

@@ -1,95 +1,93 @@
 /**
  * @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 { ObjectModeTag } from "../../kind/index.js";
 import { BaseGuard } from "../../guard/index.js";
 import { mergeObjectSchemas, objectSchema, omitObjectSchema, partialObjectSchema, pickObjectSchema, readObjectConstructorSchema, readObjectKeySelection, readObjectMethodSchema } from "./schema.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 class ObjectGuard extends BaseGuard {
-    /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
-     */
     constructor(schema) {
         super(readObjectConstructorSchema(schema));
         Object.freeze(this);
     }
-    /**
-     * @brief extend.
-           */
     extend(extension) {
         return extendObjectGuard(this, extension);
     }
-    /**
-     * @brief pick.
-           */
     pick(keys) {
         return pickObjectGuard(this, keys);
     }
-    /**
-     * @brief omit.
-           */
     omit(keys) {
         return omitObjectGuard(this, keys);
     }
-    /**
-     * @brief partial.
-         */
     partial() {
         return partialObjectGuard(this);
     }
 }
 /**
- * @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 function object(shape) {
     return new ObjectGuard(objectSchema(shape, 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 function strictObject(shape) {
     return new ObjectGuard(objectSchema(shape, ObjectModeTag.Strict));
 }
 /**
- * @brief extend.
+ * @brief Execute extend.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function extend(guard, extension) {
     return extendObjectGuard(guard, extension);
 }
 /**
- * @brief pick.
+ * @brief Execute pick.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function pick(guard, keys) {
     return pickObjectGuard(guard, keys);
 }
 /**
- * @brief omit.
+ * @brief Execute omit.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function omit(guard, keys) {
     return omitObjectGuard(guard, keys);
 }
 /**
- * @brief partial.
+ * @brief Execute partial.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function partial(guard) {
     return partialObjectGuard(guard);
 }
 /**
- * @brief extend object guard.
+ * @brief Execute extend object guard.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function extendObjectGuard(guard, extension) {
     const schema = readObjectMethodSchema(guard, "object extend receiver");
     return new ObjectGuard(mergeObjectSchemas(schema, objectSchema(extension, schema.mode)));
 }
 /**
- * @brief pick object guard.
+ * @brief Execute pick object guard.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function pickObjectGuard(guard, keys) {
     const schema = readObjectMethodSchema(guard, "object pick receiver");
@@ -97,7 +95,8 @@ function pickObjectGuard(guard, keys) {
     return new ObjectGuard(pickObjectSchema(schema, selection));
 }
 /**
- * @brief omit object guard.
+ * @brief Execute omit object guard.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function omitObjectGuard(guard, keys) {
     const schema = readObjectMethodSchema(guard, "object omit receiver");
@@ -105,7 +104,8 @@ function omitObjectGuard(guard, keys) {
     return new ObjectGuard(omitObjectSchema(schema, selection));
 }
 /**
- * @brief partial object guard.
+ * @brief Execute partial object guard.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function partialObjectGuard(guard) {
     const schema = readObjectMethodSchema(guard, "object partial receiver");

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

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public object builder aggregation.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export { ObjectGuard, extend, object, omit, partial, pick, strictObject } from "./guard.js";
 export type { InferObject, MergeObjectShapes, ObjectGuardMode, ObjectShape, OmitObjectShape, PartialObjectShape, PickObjectShape } from "./types.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/object/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,WAAW,EACX,MAAM,EACN,MAAM,EACN,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,eAAe,EAChB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builders/object/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACH,WAAW,EACX,MAAM,EACN,MAAM,EACN,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,YAAY,EACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACR,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,eAAe,EAClB,MAAM,YAAY,CAAC"}

package/dist/builders/object/index.js

@@ -1,5 +1,7 @@
 /**
  * @file index.ts
  * @brief Public object builder aggregation.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export { ObjectGuard, extend, object, omit, partial, pick, strictObject } from "./guard.js";

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

@@ -1,44 +1,90 @@
 /**
  * @file schema.ts
  * @brief Object schema construction and shape rewrites.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { ObjectModeTag } from "../../kind/index.js";
 import type { ObjectEntry, ObjectSchema } from "../../schema/index.js";
 import type { ObjectShape } from "./types.js";
 /**
- * @brief object schema.
+ * @brief Normalize an object shape into ordered entries and lookup metadata.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare function objectSchema(shape: ObjectShape, mode: ObjectModeTag): ObjectSchema;
 /**
- * @brief object schema from entries.
+ * @brief Rebuild object metadata after shape transformations.
+ * @details Duplicate keys are rejected here so pick/omit/extend cannot create
+ * a schema that disagrees with its strict-key lookup table.
  */
 export declare function objectSchemaFromEntries(sourceEntries: readonly ObjectEntry[], mode: ObjectModeTag): ObjectSchema;
 /**
- * @brief read object constructor schema.
+ * @brief Validate the schema value handed to an ObjectGuard constructor.
+ * @details Constructors are public JavaScript entry points, so the guard checks
+ * both the TypeSea schema marker and the object-schema tag before storing the
+ * value. This prevents forged objects from bypassing builder invariants.
+ * @param schema Candidate schema supplied to the constructor.
+ * @returns Object schema accepted by the constructor.
  */
 export declare function readObjectConstructorSchema(schema: unknown): ObjectSchema;
 /**
- * @brief read object method schema.
+ * @brief Extract an object schema from another guard for object-only methods.
+ * @details Methods such as merge and extension compose object shapes. Accepting
+ * a scalar guard here would build an impossible schema, so the check is kept at
+ * the API edge with the caller-facing label in the error message.
+ * @param guard Candidate TypeSea guard.
+ * @param label Human-readable API label used in thrown errors.
+ * @returns Object schema owned by the supplied guard.
  */
 export declare function readObjectMethodSchema(guard: unknown, label: string): ObjectSchema;
 /**
- * @brief merge object schemas.
+ * @brief Merge two object schemas while letting extension keys override base keys.
+ * @details Existing base order is preserved for stable diagnostics and codegen.
+ * Extension-only keys are appended afterward, and the base strict/open mode is
+ * retained so shape extension does not silently change excess-key policy.
+ * @param base Source object schema being extended.
+ * @param extension Object schema whose matching keys replace base entries.
+ * @returns Rebuilt object schema with fresh lookup metadata.
  */
 export declare function mergeObjectSchemas(base: ObjectSchema, extension: ObjectSchema): ObjectSchema;
 /**
- * @brief pick object schema.
+ * @brief Build an object schema containing only a validated key selection.
+ * @details The caller has already checked that keys are known and unique. This
+ * function preserves selection order so user-requested projection order is also
+ * the order used by diagnostics and generated object checks.
+ * @param schema Source object schema.
+ * @param keys Validated key selection.
+ * @returns Rebuilt object schema containing only selected entries.
  */
 export declare function pickObjectSchema(schema: ObjectSchema, keys: readonly string[]): ObjectSchema;
 /**
- * @brief omit object schema.
+ * @brief Build an object schema with a validated key selection removed.
+ * @details Entries not listed for removal keep their original relative order
+ * and presence metadata. The object mode is preserved across the rewrite.
+ * @param schema Source object schema.
+ * @param keys Validated key selection to remove.
+ * @returns Rebuilt object schema without the selected entries.
  */
 export declare function omitObjectSchema(schema: ObjectSchema, keys: readonly string[]): ObjectSchema;
 /**
- * @brief partial object schema.
+ * @brief Convert every object entry to optional presence.
+ * @details The child schemas are not wrapped or cloned; only field presence is
+ * rewritten. This keeps value-domain wrappers such as nullable and brand exactly
+ * as they were on the original entries.
+ * @param schema Source object schema.
+ * @returns Rebuilt object schema with optional entries.
  */
 export declare function partialObjectSchema(schema: ObjectSchema): ObjectSchema;
 /**
- * @brief read object key selection.
+ * @brief Validate the key list supplied to object pick and omit operations.
+ * @details The returned array contains only known, unique string keys. This
+ * preflight keeps later schema rewriting simple and prevents silently selecting
+ * fields that were never part of the source object schema.
+ * @param keys Candidate key list from public API calls.
+ * @param schema Object schema whose keys define the valid selection domain.
+ * @param label Human-readable API label used in thrown errors.
+ * @returns Ordered key selection accepted by the object builder.
  */
 export declare function readObjectKeySelection(keys: unknown, schema: ObjectSchema, label: string): readonly string[];
 //# sourceMappingURL=schema.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/builders/object/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAO7B,OAAO,KAAK,EACV,WAAW,EAEX,YAAY,EAEb,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAU9C;;GAEG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,aAAa,GAClB,YAAY,CAsBd;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,SAAS,WAAW,EAAE,EACrC,IAAI,EAAE,aAAa,GAClB,YAAY,CAuBd;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAMlF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,YAAY,GACtB,YAAY,CAed;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,YAAY,CAad;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,YAAY,CASd;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAatE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,GACZ,SAAS,MAAM,EAAE,CAmBnB"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/builders/object/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACH,aAAa,EAGhB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,KAAK,EACR,WAAW,EAEX,YAAY,EAEf,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAY9C;;;;GAIG;AACH,wBAAgB,YAAY,CACxB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,aAAa,GACpB,YAAY,CAsBd;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACnC,aAAa,EAAE,SAAS,WAAW,EAAE,EACrC,IAAI,EAAE,aAAa,GACpB,YAAY,CAuBd;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAMlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAC9B,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,YAAY,GACxB,YAAY,CAed;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACxB,YAAY,CAad;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACxB,YAAY,CASd;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAatE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,GACd,SAAS,MAAM,EAAE,CAmBnB"}

package/dist/builders/object/schema.js

@@ -1,12 +1,16 @@
 /**
  * @file schema.ts
  * @brief Object schema construction and shape rewrites.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { ObjectModeTag, PresenceTag, SchemaTag } from "../../kind/index.js";
 import { includesString, isRecord, isUnknownArray, readGuardSchema } from "../../internal/index.js";
 import { isSchemaValue } from "../../schema/index.js";
 /**
- * @brief object schema.
+ * @brief Normalize an object shape into ordered entries and lookup metadata.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export function objectSchema(shape, mode) {
     if (!isRecord(shape)) {
@@ -30,7 +34,9 @@ export function objectSchema(shape, mode) {
     return objectSchemaFromEntries(entries, mode);
 }
 /**
- * @brief object schema from entries.
+ * @brief Rebuild object metadata after shape transformations.
+ * @details Duplicate keys are rejected here so pick/omit/extend cannot create
+ * a schema that disagrees with its strict-key lookup table.
  */
 export function objectSchemaFromEntries(sourceEntries, mode) {
     const entries = new Array(sourceEntries.length);
@@ -57,7 +63,12 @@ export function objectSchemaFromEntries(sourceEntries, mode) {
     };
 }
 /**
- * @brief read object constructor schema.
+ * @brief Validate the schema value handed to an ObjectGuard constructor.
+ * @details Constructors are public JavaScript entry points, so the guard checks
+ * both the TypeSea schema marker and the object-schema tag before storing the
+ * value. This prevents forged objects from bypassing builder invariants.
+ * @param schema Candidate schema supplied to the constructor.
+ * @returns Object schema accepted by the constructor.
  */
 export function readObjectConstructorSchema(schema) {
     if (!isSchemaValue(schema) || schema.tag !== SchemaTag.Object) {
@@ -66,7 +77,13 @@ export function readObjectConstructorSchema(schema) {
     return schema;
 }
 /**
- * @brief read object method schema.
+ * @brief Extract an object schema from another guard for object-only methods.
+ * @details Methods such as merge and extension compose object shapes. Accepting
+ * a scalar guard here would build an impossible schema, so the check is kept at
+ * the API edge with the caller-facing label in the error message.
+ * @param guard Candidate TypeSea guard.
+ * @param label Human-readable API label used in thrown errors.
+ * @returns Object schema owned by the supplied guard.
  */
 export function readObjectMethodSchema(guard, label) {
     const schema = readGuardSchema(guard, label);
@@ -76,7 +93,13 @@ export function readObjectMethodSchema(guard, label) {
     return schema;
 }
 /**
- * @brief merge object schemas.
+ * @brief Merge two object schemas while letting extension keys override base keys.
+ * @details Existing base order is preserved for stable diagnostics and codegen.
+ * Extension-only keys are appended afterward, and the base strict/open mode is
+ * retained so shape extension does not silently change excess-key policy.
+ * @param base Source object schema being extended.
+ * @param extension Object schema whose matching keys replace base entries.
+ * @returns Rebuilt object schema with fresh lookup metadata.
  */
 export function mergeObjectSchemas(base, extension) {
     const entries = [];
@@ -95,7 +118,13 @@ export function mergeObjectSchemas(base, extension) {
     return objectSchemaFromEntries(entries, base.mode);
 }
 /**
- * @brief pick object schema.
+ * @brief Build an object schema containing only a validated key selection.
+ * @details The caller has already checked that keys are known and unique. This
+ * function preserves selection order so user-requested projection order is also
+ * the order used by diagnostics and generated object checks.
+ * @param schema Source object schema.
+ * @param keys Validated key selection.
+ * @returns Rebuilt object schema containing only selected entries.
  */
 export function pickObjectSchema(schema, keys) {
     const entries = new Array(keys.length);
@@ -112,7 +141,12 @@ export function pickObjectSchema(schema, keys) {
     return objectSchemaFromEntries(entries, schema.mode);
 }
 /**
- * @brief omit object schema.
+ * @brief Build an object schema with a validated key selection removed.
+ * @details Entries not listed for removal keep their original relative order
+ * and presence metadata. The object mode is preserved across the rewrite.
+ * @param schema Source object schema.
+ * @param keys Validated key selection to remove.
+ * @returns Rebuilt object schema without the selected entries.
  */
 export function omitObjectSchema(schema, keys) {
     const entries = [];
@@ -125,7 +159,12 @@ export function omitObjectSchema(schema, keys) {
     return objectSchemaFromEntries(entries, schema.mode);
 }
 /**
- * @brief partial object schema.
+ * @brief Convert every object entry to optional presence.
+ * @details The child schemas are not wrapped or cloned; only field presence is
+ * rewritten. This keeps value-domain wrappers such as nullable and brand exactly
+ * as they were on the original entries.
+ * @param schema Source object schema.
+ * @returns Rebuilt object schema with optional entries.
  */
 export function partialObjectSchema(schema) {
     const entries = new Array(schema.entries.length);
@@ -142,7 +181,14 @@ export function partialObjectSchema(schema) {
     return objectSchemaFromEntries(entries, schema.mode);
 }
 /**
- * @brief read object key selection.
+ * @brief Validate the key list supplied to object pick and omit operations.
+ * @details The returned array contains only known, unique string keys. This
+ * preflight keeps later schema rewriting simple and prevents silently selecting
+ * fields that were never part of the source object schema.
+ * @param keys Candidate key list from public API calls.
+ * @param schema Object schema whose keys define the valid selection domain.
+ * @param label Human-readable API label used in thrown errors.
+ * @returns Ordered key selection accepted by the object builder.
  */
 export function readObjectKeySelection(keys, schema, label) {
     if (!isUnknownArray(keys)) {
@@ -165,7 +211,13 @@ export function readObjectKeySelection(keys, schema, label) {
     return selected;
 }
 /**
- * @brief find object entry.
+ * @brief Find an object entry by key using the ordered entry vector.
+ * @details The ordered vector is the source of truth for diagnostic and codegen
+ * order. The lookup table proves membership, while this helper recovers the
+ * full entry payload.
+ * @param entries Ordered object entries.
+ * @param key Field name to locate.
+ * @returns Matching object entry, or undefined when absent.
  */
 function findObjectEntry(entries, key) {
     for (let index = 0; index < entries.length; index += 1) {
@@ -177,13 +229,21 @@ function findObjectEntry(entries, key) {
     return undefined;
 }
 /**
- * @brief make object key lookup.
+ * @brief Allocate a null-prototype lookup table for object schema keys.
+ * @details User field names may overlap with Object.prototype properties. A
+ * null-prototype table keeps membership checks data-only and avoids inherited
+ * keys participating in schema construction.
+ * @returns Empty key lookup table used by object schemas.
  */
 function makeObjectKeyLookup() {
     return Object.create(null);
 }
 /**
- * @brief define object key.
+ * @brief Install one immutable key marker into an object-schema lookup table.
+ * @details Object keys are defined as own data properties so membership checks
+ * cannot be influenced by prototype state or later mutation of the table.
+ * @param target Null-prototype key lookup table.
+ * @param key Field name to mark as present.
  */
 function defineObjectKey(target, key) {
     Object.defineProperty(target, key, {
@@ -194,13 +254,23 @@ function defineObjectKey(target, key) {
     });
 }
 /**
- * @brief has object key.
+ * @brief Test object-schema key membership through the prepared lookup table.
+ * @details The table stores immutable true values, so direct indexed access is
+ * sufficient and avoids repeated descriptor allocation during builder work.
+ * @param keyLookup Null-prototype lookup table from the object schema.
+ * @param key Candidate field name.
+ * @returns True when the key belongs to the object schema.
  */
 function hasObjectKey(keyLookup, key) {
     return keyLookup[key] === true;
 }
 /**
- * @brief normalize object entry schema.
+ * @brief Split object-field presence from value-domain schema wrappers.
+ * @details Optional is the only wrapper that changes field presence. Other
+ * wrappers are rebuilt around the normalized inner schema so optionality can
+ * propagate outward without losing nullable, brand, or refinement behavior.
+ * @param schema Field schema supplied by the object builder.
+ * @returns Normalized child schema and required/optional presence tag.
  */
 function normalizeObjectEntrySchema(schema) {
     switch (schema.tag) {
@@ -240,7 +310,14 @@ function normalizeObjectEntrySchema(schema) {
     }
 }
 /**
- * @brief normalize wrapped object entry schema.
+ * @brief Rebuild a wrapper after normalizing its inner object-field schema.
+ * @details When the inner schema stays required, the original wrapper can be
+ * kept unchanged. When optionality is discovered inside, the wrapper is rebuilt
+ * around the normalized child and the field presence becomes optional.
+ * @param inner Inner schema carried by the wrapper.
+ * @param wrap Function that rebuilds the same wrapper around a new child.
+ * @param original Original wrapper schema.
+ * @returns Normalized schema and presence tag for the object field.
  */
 function normalizeWrappedObjectEntrySchema(inner, wrap, original) {
     const normalized = normalizeObjectEntrySchema(inner);

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

@@ -1,63 +1,37 @@
 /**
  * @file types.ts
  * @brief Object builder type algebra.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import type { BaseGuard, Guard, GuardPresence, GuardValue, Infer, Presence } from "../../guard/index.js";
 import type { ObjectModeTag } from "../../kind/index.js";
-/**
- * @brief object shape.
- */
 export type ObjectShape = Readonly<Record<string, Guard<unknown, Presence>>>;
-/**
- * @brief object guard mode.
- */
 export type ObjectGuardMode = typeof ObjectModeTag.Passthrough | typeof ObjectModeTag.Strict;
-/**
- * @brief optional keys.
- */
 export type OptionalKeys<TShape extends ObjectShape> = {
     [TKey in keyof TShape]-?: GuardPresence<TShape[TKey]> extends "optional" ? TKey : never;
 }[keyof TShape];
-/**
- * @brief required keys.
- */
 export type RequiredKeys<TShape extends ObjectShape> = {
     [TKey in keyof TShape]-?: GuardPresence<TShape[TKey]> extends "optional" ? never : TKey;
 }[keyof TShape];
 /**
- * @brief infer object.
+ * @brief Infer required and optional object fields from guard presence tags.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export type InferObject<TShape extends ObjectShape> = Simplify<{
     readonly [TKey in RequiredKeys<TShape>]: Infer<TShape[TKey]>;
 } & {
     readonly [TKey in OptionalKeys<TShape>]?: GuardValue<TShape[TKey]>;
 }>;
-/**
- * @brief simplify.
- */
 export type Simplify<TValue> = {
     readonly [TKey in keyof TValue]: TValue[TKey];
 } & {};
-/**
- * @brief merge object shapes.
- */
 export type MergeObjectShapes<TBase extends ObjectShape, TExtension extends ObjectShape> = Simplify<Omit<TBase, keyof TExtension> & TExtension>;
-/**
- * @brief partial object shape.
- */
 export type PartialObjectShape<TShape extends ObjectShape> = {
     readonly [TKey in keyof TShape]: BaseGuard<GuardValue<TShape[TKey]>, "optional">;
 };
-/**
- * @brief pick object shape.
- */
 export type PickObjectShape<TShape extends ObjectShape, TKey extends string> = Pick<TShape, Extract<keyof TShape, TKey>>;
-/**
- * @brief omit object shape.
- */
 export type OmitObjectShape<TShape extends ObjectShape, TKey extends string> = Omit<TShape, Extract<keyof TShape, TKey>>;
-/**
- * @brief string key of.
- */
 export type StringKeyOf<TValue> = Extract<keyof TValue, string>;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/object/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EACL,aAAa,EACb,UAAU,EACV,KAAK,EACL,QAAQ,EACT,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE7E;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,OAAO,aAAa,CAAC,WAAW,GAChC,OAAO,aAAa,CAAC,MAAM,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,WAAW,IAAI;KACpD,IAAI,IAAI,MAAM,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,UAAU,GACpE,IAAI,GACJ,KAAK;CACV,CAAC,MAAM,MAAM,CAAC,CAAC;AAEhB;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,WAAW,IAAI;KACpD,IAAI,IAAI,MAAM,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,UAAU,GACpE,KAAK,GACL,IAAI;CACT,CAAC,MAAM,MAAM,CAAC,CAAC;AAEhB;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,WAAW,IAAI,QAAQ,CAC5D;IACE,QAAQ,EAAE,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAC7D,GAAG;IACF,QAAQ,EAAE,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACnE,CACF,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,MAAM,IAAI;IAC7B,QAAQ,EAAE,IAAI,IAAI,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;CAC9C,GAAG,EAAE,CAAC;AAEP;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAC3B,KAAK,SAAS,WAAW,EACzB,UAAU,SAAS,WAAW,IAC5B,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,UAAU,CAAC,GAAG,UAAU,CAAC,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,MAAM,SAAS,WAAW,IAAI;IAC3D,QAAQ,EAAE,IAAI,IAAI,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC;CACjF,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,CACzB,MAAM,SAAS,WAAW,EAC1B,IAAI,SAAS,MAAM,IACjB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,eAAe,CACzB,MAAM,SAAS,WAAW,EAC1B,IAAI,SAAS,MAAM,IACjB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,MAAM,EAAE,MAAM,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/object/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACR,SAAS,EACT,KAAK,EACL,aAAa,EACb,UAAU,EACV,KAAK,EACL,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE7E,MAAM,MAAM,eAAe,GACrB,OAAO,aAAa,CAAC,WAAW,GAChC,OAAO,aAAa,CAAC,MAAM,CAAC;AAElC,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,WAAW,IAAI;KAClD,IAAI,IAAI,MAAM,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,UAAU,GAClE,IAAI,GACJ,KAAK;CACd,CAAC,MAAM,MAAM,CAAC,CAAC;AAEhB,MAAM,MAAM,YAAY,CAAC,MAAM,SAAS,WAAW,IAAI;KAClD,IAAI,IAAI,MAAM,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,UAAU,GAClE,KAAK,GACL,IAAI;CACb,CAAC,MAAM,MAAM,CAAC,CAAC;AAEhB;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,WAAW,IAAI,QAAQ,CAC1D;IACI,QAAQ,EAAE,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CAC/D,GAAG;IACA,QAAQ,EAAE,IAAI,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACrE,CACJ,CAAC;AAEF,MAAM,MAAM,QAAQ,CAAC,MAAM,IAAI;IAC3B,QAAQ,EAAE,IAAI,IAAI,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;CAChD,GAAG,EAAE,CAAC;AAEP,MAAM,MAAM,iBAAiB,CACzB,KAAK,SAAS,WAAW,EACzB,UAAU,SAAS,WAAW,IAC9B,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,UAAU,CAAC,GAAG,UAAU,CAAC,CAAC;AAEzD,MAAM,MAAM,kBAAkB,CAAC,MAAM,SAAS,WAAW,IAAI;IACzD,QAAQ,EAAE,IAAI,IAAI,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC;CACnF,CAAC;AAEF,MAAM,MAAM,eAAe,CACvB,MAAM,SAAS,WAAW,EAC1B,IAAI,SAAS,MAAM,IACnB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AAE9C,MAAM,MAAM,eAAe,CACvB,MAAM,SAAS,WAAW,EAC1B,IAAI,SAAS,MAAM,IACnB,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AAE9C,MAAM,MAAM,WAAW,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,MAAM,EAAE,MAAM,CAAC,CAAC"}

package/dist/builders/object/types.js

@@ -1,5 +1,7 @@
 /**
  * @file types.ts
  * @brief Object builder type algebra.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export {};

package/dist/builders/scalar.d.ts

@@ -1,39 +1,60 @@
 /**
  * @file scalar.ts
  * @brief Primitive and literal guard builders.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { BaseGuard, NumberGuard, StringGuard } from "../guard/index.js";
 import type { LiteralValue } from "../schema/index.js";
 /**
- * @brief string guard.
+ * @brief Shared string guard singleton.
+ * @details Primitive guards are immutable, so exporting one instance avoids
+ * allocation for the common `t.string` path.
  */
 export declare const stringGuard: StringGuard<"required">;
 /**
- * @brief unknown guard.
+ * @brief Shared unknown guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare const unknownGuard: BaseGuard<unknown, "required">;
 /**
- * @brief never guard.
+ * @brief Shared never guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare const neverGuard: BaseGuard<never, "required">;
 /**
- * @brief number guard.
+ * @brief Shared finite number guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare const numberGuard: NumberGuard<"required">;
 /**
- * @brief bigint guard.
+ * @brief Shared bigint guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare const bigintGuard: BaseGuard<bigint, "required">;
 /**
- * @brief symbol guard.
+ * @brief Shared symbol guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare const symbolGuard: BaseGuard<symbol, "required">;
 /**
- * @brief boolean guard.
+ * @brief Shared boolean guard singleton.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare const booleanGuard: BaseGuard<boolean, "required">;
 /**
- * @brief literal.
+ * @brief Build a literal guard after rejecting non-literal runtime values.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param value Literal value to match with Object.is.
+ * @returns Fresh guard for exactly the supplied literal.
+ * @throws TypeError when the value cannot be represented as a TypeSea literal.
  */
 export declare function literal<const TValue extends LiteralValue>(value: TValue): BaseGuard<TValue>;
 //# sourceMappingURL=scalar.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scalar.d.ts","sourceRoot":"","sources":["../../src/builders/scalar.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,SAAS,EACT,WAAW,EACX,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;GAEG;AACH,eAAO,MAAM,WAAW,yBAGtB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY,gCAEvB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU,8BAErB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,yBAGtB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,+BAEtB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,+BAEtB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY,gCAEvB,CAAC;AAEH;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,CAAC,MAAM,SAAS,YAAY,EACvD,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,MAAM,CAAC,CAQnB"}
+{"version":3,"file":"scalar.d.ts","sourceRoot":"","sources":["../../src/builders/scalar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACH,SAAS,EACT,WAAW,EACX,WAAW,EACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD;;;;GAIG;AACH,eAAO,MAAM,WAAW,yBAGtB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY,gCAEvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU,8BAErB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,yBAGtB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,+BAEtB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,+BAEtB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY,gCAEvB,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,CAAC,MAAM,SAAS,YAAY,EACrD,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,MAAM,CAAC,CAYnB"}