typesea 0.1.0 → 0.2.0

package/dist/guard/read.d.ts

@@ -1,42 +1,95 @@
 /**
  * @file read.ts
  * @brief Guard receiver and constructor validation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import type { NumberSchema, Schema, StringSchema } from "../schema/index.js";
 /**
- * @brief read guard schema.
+ * @brief Read schema from a verified guard receiver.
+ * @details Constructed guards take the WeakSet fast path; forged structural
+ * guards must expose a valid own data schema before use. The fallback exists
+ * because public methods can be detached from their instance in JavaScript.
+ * @param guard Candidate receiver or guard-like value.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns Valid runtime schema carried by the guard.
+ * @throws TypeError when the receiver is not a valid TypeSea guard.
  */
 export declare function readGuardSchema(guard: unknown, label: string): Schema;
 /**
- * @brief read string method schema.
+ * @brief Read and require a string schema from a method receiver.
+ * @param guard Candidate receiver.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns String schema carried by the receiver.
+ * @throws TypeError when the receiver is not a string guard.
+ * @details StringGuard methods share this gate so subtype-specific helpers do
+ * not duplicate receiver validation or accept forged schemas.
  */
 export declare function readStringMethodSchema(guard: unknown, label: string): StringSchema;
 /**
- * @brief read number method schema.
+ * @brief Read and require a number schema from a method receiver.
+ * @param guard Candidate receiver.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns Number schema carried by the receiver.
+ * @throws TypeError when the receiver is not a number guard.
+ * @details NumberGuard methods must fail before reading numeric check vectors
+ * when a receiver is detached or structurally forged.
  */
 export declare function readNumberMethodSchema(guard: unknown, label: string): NumberSchema;
 /**
- * @brief read constructor schema.
+ * @brief Validate and freeze a generic guard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns Frozen schema accepted by BaseGuard.
+ * @throws TypeError when the schema is malformed.
+ * @details Constructors are the only place that accepts mutable schema records.
+ * Freezing here lets normal method calls use the registry fast path later.
  */
 export declare function readConstructorSchema(schema: unknown): Schema;
 /**
- * @brief read string constructor schema.
+ * @brief Validate a StringGuard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns String schema accepted by StringGuard.
+ * @throws TypeError when the schema is not a string schema.
+ * @details Specialized guards keep their schema tag invariant at construction,
+ * so hot method calls only need to verify receiver identity.
  */
 export declare function readStringConstructorSchema(schema: unknown): StringSchema;
 /**
- * @brief read number constructor schema.
+ * @brief Validate a NumberGuard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns Number schema accepted by NumberGuard.
+ * @throws TypeError when the schema is not a number schema.
+ * @details Rejecting non-number schemas at construction prevents mixed scalar
+ * helper methods from observing incompatible check vectors.
  */
 export declare function readNumberConstructorSchema(schema: unknown): NumberSchema;
 /**
- * @brief check refinement input.
+ * @brief Validate refinement API inputs.
+ * @param predicate Candidate refinement predicate.
+ * @param name Candidate diagnostic name.
+ * @throws TypeError when either input has the wrong runtime type.
+ * @details Refinements execute user code by design. This gate narrows the call
+ * target and diagnostic label before the schema stores them.
  */
 export declare function checkRefinementInput(predicate: unknown, name: unknown): asserts predicate is (value: unknown) => boolean;
 /**
- * @brief check string length bound.
+ * @brief Validate a non-negative string length bound.
+ * @param value Candidate bound.
+ * @param label Bound label used in RangeError messages.
+ * @returns The validated bound.
+ * @throws RangeError when the bound is negative or non-integer.
+ * @details Bounds are checked once at builder time so generated validators can
+ * emit straight comparisons without defensive range checks.
  */
 export declare function checkStringLengthBound(value: number, label: string): number;
 /**
- * @brief check finite number bound.
+ * @brief Validate a finite numeric bound.
+ * @param value Candidate bound.
+ * @param label Bound label used in RangeError messages.
+ * @returns The validated bound.
+ * @throws RangeError when the bound is not finite.
+ * @details Finite bounds keep interpreter, plan, and emitted code semantics
+ * aligned for comparisons such as gte and lte.
  */
 export declare function checkFiniteNumberBound(value: number, label: string): number;
 //# sourceMappingURL=read.d.ts.map

package/dist/guard/read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/guard/read.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK7E;;GAEG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CAYR;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAalF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAalF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAK7D;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,OAAO,EAClB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAOlD;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3E"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/guard/read.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK7E;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC3B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACd,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAalF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAalF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAK7D;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CAKzE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAChC,SAAS,EAAE,OAAO,EAClB,IAAI,EAAE,OAAO,GACd,OAAO,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAOlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3E"}

package/dist/guard/read.js

@@ -1,29 +1,48 @@
 /**
  * @file read.ts
  * @brief Guard receiver and constructor validation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import { SchemaTag } from "../kind/index.js";
 import { freezeSchema, isSchemaValue } from "../schema/index.js";
 import { isRecord } from "./props.js";
 import { isConstructedGuard } from "./registry.js";
 /**
- * @brief read guard schema.
+ * @brief Read schema from a verified guard receiver.
+ * @details Constructed guards take the WeakSet fast path; forged structural
+ * guards must expose a valid own data schema before use. The fallback exists
+ * because public methods can be detached from their instance in JavaScript.
+ * @param guard Candidate receiver or guard-like value.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns Valid runtime schema carried by the guard.
+ * @throws TypeError when the receiver is not a valid TypeSea guard.
  */
 export function readGuardSchema(guard, label) {
     if (isConstructedGuard(guard)) {
+        /*
+         * Constructed guards have already frozen their schema, so the registry
+         * path avoids repeating structural schema validation for normal calls.
+         */
         return guard.schema;
     }
     if (!isRecord(guard)) {
         throw new TypeError(`${label} must be a TypeSea guard`);
     }
-    const schema = guard["schema"];
+    const schema = readOwnDataProperty(guard, "schema");
     if (!isSchemaValue(schema)) {
         throw new TypeError(`${label} must contain a valid TypeSea schema`);
     }
     return schema;
 }
 /**
- * @brief read string method schema.
+ * @brief Read and require a string schema from a method receiver.
+ * @param guard Candidate receiver.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns String schema carried by the receiver.
+ * @throws TypeError when the receiver is not a string guard.
+ * @details StringGuard methods share this gate so subtype-specific helpers do
+ * not duplicate receiver validation or accept forged schemas.
  */
 export function readStringMethodSchema(guard, label) {
     if (isConstructedGuard(guard)) {
@@ -40,7 +59,13 @@ export function readStringMethodSchema(guard, label) {
     return schema;
 }
 /**
- * @brief read number method schema.
+ * @brief Read and require a number schema from a method receiver.
+ * @param guard Candidate receiver.
+ * @param label Human-readable label used in TypeError messages.
+ * @returns Number schema carried by the receiver.
+ * @throws TypeError when the receiver is not a number guard.
+ * @details NumberGuard methods must fail before reading numeric check vectors
+ * when a receiver is detached or structurally forged.
  */
 export function readNumberMethodSchema(guard, label) {
     if (isConstructedGuard(guard)) {
@@ -57,7 +82,12 @@ export function readNumberMethodSchema(guard, label) {
     return schema;
 }
 /**
- * @brief read constructor schema.
+ * @brief Validate and freeze a generic guard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns Frozen schema accepted by BaseGuard.
+ * @throws TypeError when the schema is malformed.
+ * @details Constructors are the only place that accepts mutable schema records.
+ * Freezing here lets normal method calls use the registry fast path later.
  */
 export function readConstructorSchema(schema) {
     if (!isSchemaValue(schema)) {
@@ -66,7 +96,12 @@ export function readConstructorSchema(schema) {
     return freezeSchema(schema);
 }
 /**
- * @brief read string constructor schema.
+ * @brief Validate a StringGuard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns String schema accepted by StringGuard.
+ * @throws TypeError when the schema is not a string schema.
+ * @details Specialized guards keep their schema tag invariant at construction,
+ * so hot method calls only need to verify receiver identity.
  */
 export function readStringConstructorSchema(schema) {
     if (!isSchemaValue(schema) || schema.tag !== SchemaTag.String) {
@@ -75,7 +110,12 @@ export function readStringConstructorSchema(schema) {
     return schema;
 }
 /**
- * @brief read number constructor schema.
+ * @brief Validate a NumberGuard constructor schema.
+ * @param schema Candidate runtime schema.
+ * @returns Number schema accepted by NumberGuard.
+ * @throws TypeError when the schema is not a number schema.
+ * @details Rejecting non-number schemas at construction prevents mixed scalar
+ * helper methods from observing incompatible check vectors.
  */
 export function readNumberConstructorSchema(schema) {
     if (!isSchemaValue(schema) || schema.tag !== SchemaTag.Number) {
@@ -84,7 +124,12 @@ export function readNumberConstructorSchema(schema) {
     return schema;
 }
 /**
- * @brief check refinement input.
+ * @brief Validate refinement API inputs.
+ * @param predicate Candidate refinement predicate.
+ * @param name Candidate diagnostic name.
+ * @throws TypeError when either input has the wrong runtime type.
+ * @details Refinements execute user code by design. This gate narrows the call
+ * target and diagnostic label before the schema stores them.
  */
 export function checkRefinementInput(predicate, name) {
     if (typeof predicate !== "function") {
@@ -95,7 +140,13 @@ export function checkRefinementInput(predicate, name) {
     }
 }
 /**
- * @brief check string length bound.
+ * @brief Validate a non-negative string length bound.
+ * @param value Candidate bound.
+ * @param label Bound label used in RangeError messages.
+ * @returns The validated bound.
+ * @throws RangeError when the bound is negative or non-integer.
+ * @details Bounds are checked once at builder time so generated validators can
+ * emit straight comparisons without defensive range checks.
  */
 export function checkStringLengthBound(value, label) {
     if (!Number.isInteger(value) || value < 0) {
@@ -104,7 +155,13 @@ export function checkStringLengthBound(value, label) {
     return value;
 }
 /**
- * @brief check finite number bound.
+ * @brief Validate a finite numeric bound.
+ * @param value Candidate bound.
+ * @param label Bound label used in RangeError messages.
+ * @returns The validated bound.
+ * @throws RangeError when the bound is not finite.
+ * @details Finite bounds keep interpreter, plan, and emitted code semantics
+ * aligned for comparisons such as gte and lte.
  */
 export function checkFiniteNumberBound(value, label) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -112,3 +169,19 @@ export function checkFiniteNumberBound(value, label) {
     }
     return value;
 }
+/**
+ * @brief Read one own data slot from a structural guard receiver.
+ * @param value Candidate receiver.
+ * @param key Field name or symbol.
+ * @returns Stored field value, or undefined when the slot is absent.
+ * @details Structural guard support is intentionally narrow: inherited schema
+ * getters must not execute while validating detached method receivers.
+ */
+function readOwnDataProperty(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined ||
+        !Object.prototype.hasOwnProperty.call(descriptor, "value")) {
+        return undefined;
+    }
+    return descriptor.value;
+}

package/dist/guard/registry.d.ts

@@ -1,15 +1,25 @@
 /**
  * @file registry.ts
  * @brief Constructed guard receiver registry.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import type { BaseGuard } from "./base.js";
 import type { Presence } from "./types.js";
 /**
- * @brief register constructed guard.
+ * @brief Mark a guard instance as constructor-owned.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Guard instance created by TypeSea constructors.
+ * @post The value can use the fast receiver validation path.
  */
 export declare function registerConstructedGuard(value: object): void;
 /**
- * @brief is constructed guard.
+ * @brief Test whether a receiver was built by a TypeSea guard constructor.
+ * @param value Candidate receiver.
+ * @returns True when the value was registered by a TypeSea guard constructor.
+ * @details Public methods use this check to skip structural schema validation
+ * only for receivers whose schema slot was already frozen during construction.
  */
 export declare function isConstructedGuard(value: unknown): value is BaseGuard<unknown, Presence>;
 //# sourceMappingURL=registry.d.ts.map

package/dist/guard/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/guard/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAQ3C;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAEvC"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/guard/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAU3C;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,OAAO,GACf,KAAK,IAAI,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAEvC"}

package/dist/guard/registry.js

@@ -1,20 +1,32 @@
 /**
  * @file registry.ts
  * @brief Constructed guard receiver registry.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import { isRecord } from "./props.js";
 /**
- * @brief constructed guards.
+ * @brief Receiver identity table for guards constructed by TypeSea.
+ * @details Weak membership proves that a receiver passed a TypeSea constructor
+ * without adding public marker fields that user code could forge.
  */
 const constructedGuards = new WeakSet();
 /**
- * @brief register constructed guard.
+ * @brief Mark a guard instance as constructor-owned.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Guard instance created by TypeSea constructors.
+ * @post The value can use the fast receiver validation path.
  */
 export function registerConstructedGuard(value) {
     constructedGuards.add(value);
 }
 /**
- * @brief is constructed guard.
+ * @brief Test whether a receiver was built by a TypeSea guard constructor.
+ * @param value Candidate receiver.
+ * @returns True when the value was registered by a TypeSea guard constructor.
+ * @details Public methods use this check to skip structural schema validation
+ * only for receivers whose schema slot was already frozen during construction.
  */
 export function isConstructedGuard(value) {
     return isRecord(value) && constructedGuards.has(value);

package/dist/guard/string.d.ts

@@ -1,36 +1,56 @@
 /**
  * @file string.ts
  * @brief String guard implementation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import type { StringSchema } from "../schema/index.js";
 import { BaseGuard } from "./base.js";
 import type { Presence } from "./types.js";
 /**
- * @brief string guard.
- * @details Owns its state directly; methods expose receiver checks and explicit result flow.
- * @invariant Construction leaves the instance in a fully usable state before it escapes.
+ * @brief Persistent builder for string predicates.
+ * @details Refinement methods append schema checks and return fresh frozen
+ * guards, so shared guard values cannot be mutated by later chains.
  */
 export declare class StringGuard<TPresence extends Presence = "required"> extends BaseGuard<string, TPresence> {
     /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
+     * @brief Construct a frozen string guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param schema String schema backing this guard.
      */
     constructor(schema: StringSchema);
     /**
-     * @brief min.
-           */
+     * @brief Add a minimum string length.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Non-negative integer lower length bound.
+     * @returns Fresh StringGuard with an appended min check.
+     */
     min(value: number): StringGuard<TPresence>;
     /**
-     * @brief max.
-           */
+     * @brief Add a maximum string length.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Non-negative integer upper length bound.
+     * @returns Fresh StringGuard with an appended max check.
+     */
     max(value: number): StringGuard<TPresence>;
     /**
-     * @brief regex.
-             */
+     * @brief Add a regular expression check.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param pattern Plain RegExp instance to clone into the schema.
+     * @param name Diagnostic name for pattern failures.
+     * @returns Fresh StringGuard with an appended regex check.
+     */
     regex(pattern: RegExp, name: string): StringGuard<TPresence>;
     /**
-     * @brief uuid.
-         */
+     * @brief Add the built-in UUID string check.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh StringGuard with an appended uuid check.
+     */
     uuid(): StringGuard<TPresence>;
 }
 //# sourceMappingURL=string.d.ts.map

package/dist/guard/string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../src/guard/string.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAOtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,WAAW,CACtB,SAAS,SAAS,QAAQ,GAAG,UAAU,CACvC,SAAQ,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC;IAEpC;;;OAGG;gBACgB,MAAM,EAAE,YAAY;IAKvC;;aAES;IACF,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAejD;;aAES;IACF,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAejD;;eAEW;IACJ,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAqBnE;;WAEO;IACA,IAAI,IAAI,WAAW,CAAC,SAAS,CAAC;CAYtC"}
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../src/guard/string.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAOtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,WAAW,CACpB,SAAS,SAAS,QAAQ,GAAG,UAAU,CACzC,SAAQ,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC;IAElC;;;;;OAKG;gBACgB,MAAM,EAAE,YAAY;IAKvC;;;;;;OAMG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAejD;;;;;;OAMG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAejD;;;;;;;OAOG;IACI,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAyBnE;;;;;OAKG;IACI,IAAI,IAAI,WAAW,CAAC,SAAS,CAAC;CAYxC"}

package/dist/guard/string.js

@@ -1,28 +1,36 @@
 /**
  * @file string.ts
  * @brief String guard implementation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import { SchemaTag, StringCheckTag } from "../kind/index.js";
 import { BaseGuard } from "./base.js";
 import { isPlainRegExp } from "./props.js";
 import { checkStringLengthBound, readStringConstructorSchema, readStringMethodSchema } from "./read.js";
 /**
- * @brief string guard.
- * @details Owns its state directly; methods expose receiver checks and explicit result flow.
- * @invariant Construction leaves the instance in a fully usable state before it escapes.
+ * @brief Persistent builder for string predicates.
+ * @details Refinement methods append schema checks and return fresh frozen
+ * guards, so shared guard values cannot be mutated by later chains.
  */
 export class StringGuard extends BaseGuard {
     /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
+     * @brief Construct a frozen string guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param schema String schema backing this guard.
      */
     constructor(schema) {
         super(readStringConstructorSchema(schema));
         Object.freeze(this);
     }
     /**
-     * @brief min.
-           */
+     * @brief Add a minimum string length.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Non-negative integer lower length bound.
+     * @returns Fresh StringGuard with an appended min check.
+     */
     min(value) {
         const schema = readStringMethodSchema(this, "string min receiver");
         const bound = checkStringLengthBound(value, "min");
@@ -38,8 +46,12 @@ export class StringGuard extends BaseGuard {
         });
     }
     /**
-     * @brief max.
-           */
+     * @brief Add a maximum string length.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Non-negative integer upper length bound.
+     * @returns Fresh StringGuard with an appended max check.
+     */
     max(value) {
         const schema = readStringMethodSchema(this, "string max receiver");
         const bound = checkStringLengthBound(value, "max");
@@ -55,8 +67,13 @@ export class StringGuard extends BaseGuard {
         });
     }
     /**
-     * @brief regex.
-             */
+     * @brief Add a regular expression check.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param pattern Plain RegExp instance to clone into the schema.
+     * @param name Diagnostic name for pattern failures.
+     * @returns Fresh StringGuard with an appended regex check.
+     */
     regex(pattern, name) {
         if (!isPlainRegExp(pattern)) {
             throw new TypeError("regex pattern must be a plain RegExp");
@@ -65,6 +82,10 @@ export class StringGuard extends BaseGuard {
             throw new TypeError("regex name must be a string");
         }
         const schema = readStringMethodSchema(this, "string regex receiver");
+        /*
+         * Clone the pattern so later mutation of lastIndex or subclass state on
+         * the caller-owned RegExp cannot affect validation.
+         */
         return new StringGuard({
             tag: SchemaTag.String,
             checks: [
@@ -78,8 +99,11 @@ export class StringGuard extends BaseGuard {
         });
     }
     /**
-     * @brief uuid.
-         */
+     * @brief Add the built-in UUID string check.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh StringGuard with an appended uuid check.
+     */
     uuid() {
         const schema = readStringMethodSchema(this, "string uuid receiver");
         return new StringGuard({