typesea 0.1.0 → 0.2.0

package/dist/guard/base.js

@@ -1,6 +1,8 @@
 /**
  * @file base.ts
  * @brief Base guard implementation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import { SchemaTag } from "../kind/index.js";
 import { checkSchema, isSchema } from "../evaluate/index.js";
@@ -10,37 +12,62 @@ import { checkRefinementInput, readConstructorSchema, readGuardSchema } from "./
 import { defineReadonlyProperty, isStrictTrue } from "./props.js";
 import { registerConstructedGuard } from "./registry.js";
 /**
- * @brief base 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 Schema-backed guard base.
+ * @details Methods accept an unknown receiver on purpose. Public JavaScript can
+ * detach or forge methods, so every entry point re-reads the runtime schema
+ * before executing validation.
+ * @invariant The stored schema is immutable after construction.
  */
 export class BaseGuard {
     /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
+     * @brief Construct a schema-backed guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param schema Runtime schema owned by the guard.
+     * @post The schema slot is frozen and the receiver is registered for fast checks.
      */
     constructor(schema) {
         defineReadonlyProperty(this, "schema", readConstructorSchema(schema), true);
         registerConstructedGuard(this);
         if (new.target === BaseGuard) {
+            /*
+             * Direct BaseGuard instances have no subclass state. Freeze them here
+             * so user code cannot mutate the public validation object after setup.
+             */
             Object.freeze(this);
         }
     }
     /**
-     * @brief is.
-             */
+     * @brief Test whether a value satisfies this guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Candidate runtime value.
+     * @returns True when the value is accepted by the guard schema.
+     */
     is(value) {
+        /*
+         * Methods may be detached from their instance in JavaScript. Re-reading
+         * the schema from `this` makes receiver forgery fail before validation.
+         */
         return isSchema(readGuardSchema(this, "guard receiver"), value);
     }
     /**
-     * @brief check.
-             */
+     * @brief Validate a value and return explicit diagnostics.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Candidate runtime value.
+     * @returns Result carrying the value on success or frozen issues on failure.
+     */
     check(value) {
         return checkSchema(readGuardSchema(this, "guard receiver"), value);
     }
     /**
-     * @brief assert.
-             */
+     * @brief Validate a value and throw TypeSeaAssertionError on failure.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Candidate runtime value.
+     * @throws TypeSeaAssertionError when validation fails.
+     */
     assert(value) {
         const result = checkSchema(readGuardSchema(this, "guard receiver"), value);
         if (!result.ok) {
@@ -48,14 +75,20 @@ export class BaseGuard {
         }
     }
     /**
-     * @brief graph.
-           */
+     * @brief Return the optimized validation graph for introspection.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Sea-of-Nodes graph derived from the guard schema.
+     */
     graph() {
         return makeValidationPlan(readGuardSchema(this, "guard receiver")).graph;
     }
     /**
-     * @brief optional.
-         */
+     * @brief Mark this guard as optional in object shapes.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh guard whose runtime value also allows absent object keys.
+     */
     optional() {
         return new BaseGuard({
             tag: SchemaTag.Optional,
@@ -63,8 +96,11 @@ export class BaseGuard {
         });
     }
     /**
-     * @brief undefinedable.
-         */
+     * @brief Allow the explicit undefined value.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh guard wrapping this schema in Undefinedable.
+     */
     undefinedable() {
         return new BaseGuard({
             tag: SchemaTag.Undefinedable,
@@ -72,8 +108,11 @@ export class BaseGuard {
         });
     }
     /**
-     * @brief nullable.
-         */
+     * @brief Allow the explicit null value.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh guard wrapping this schema in Nullable.
+     */
     nullable() {
         return new BaseGuard({
             tag: SchemaTag.Nullable,
@@ -81,8 +120,11 @@ export class BaseGuard {
         });
     }
     /**
-     * @brief array.
-         */
+     * @brief Build an array guard using this guard as the item schema.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh array guard.
+     */
     array() {
         return new BaseGuard({
             tag: SchemaTag.Array,
@@ -90,8 +132,11 @@ export class BaseGuard {
         });
     }
     /**
-     * @brief brand.
-         */
+     * @brief Attach a compile-time brand without changing runtime validation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh branded guard with the same runtime schema.
+     */
     brand() {
         return new BaseGuard({
             tag: SchemaTag.Brand,
@@ -100,20 +145,33 @@ export class BaseGuard {
         });
     }
     /**
-     * @brief refine.
-             */
+     * @brief Append a user refinement predicate after this guard succeeds.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param predicate Function that must return the boolean literal true.
+     * @param name Diagnostic name for refinement failure.
+     * @returns Fresh refined guard.
+     */
     refine(predicate, name) {
         checkRefinementInput(predicate, name);
         return new BaseGuard({
             tag: SchemaTag.Refine,
             inner: readGuardSchema(this, "refine inner"),
+            /*
+             * The predicate is wrapped so only strict true succeeds. Truthy
+             * non-boolean values stay failures, matching the interpreter helper.
+             */
             predicate: (value) => isStrictTrue(predicate(value)),
             name
         });
     }
     /**
-     * @brief or.
-           */
+     * @brief Build a union of this guard and another guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param other Right-hand guard.
+     * @returns Fresh union guard preserving both runtime schemas.
+     */
     or(other) {
         return new BaseGuard({
             tag: SchemaTag.Union,
@@ -124,8 +182,12 @@ export class BaseGuard {
         });
     }
     /**
-     * @brief intersect.
-           */
+     * @brief Build an intersection of this guard and another guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param other Right-hand guard.
+     * @returns Fresh intersection guard requiring both schemas to pass.
+     */
     intersect(other) {
         return new BaseGuard({
             tag: SchemaTag.Intersection,

package/dist/guard/error.d.ts

@@ -1,18 +1,23 @@
 /**
  * @file error.ts
  * @brief TypeSea assertion error.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import type { Issue } from "../issue/index.js";
 /**
- * @brief type sea assertion error.
- * @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 Error thrown by assert() after validation has already produced issues.
+ * @details The issue array is copied before publication so callers cannot mutate
+ * diagnostic state through the error object.
  */
 export declare class TypeSeaAssertionError extends Error {
     readonly issues: readonly Issue[];
     /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
+     * @brief Construct an assertion error from validation issues.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param issues Issues produced by checkSchema.
+     * @post Published issues are copied and exposed through a readonly property.
      */
     constructor(issues: readonly Issue[]);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/guard/error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAI/C;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAwB,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAEjD;;;OAGG;gBACgB,MAAM,EAAE,SAAS,KAAK,EAAE;CAK5C"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/guard/error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAI/C;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC5C,SAAwB,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAEjD;;;;;;OAMG;gBACgB,MAAM,EAAE,SAAS,KAAK,EAAE;CAK9C"}

package/dist/guard/error.js

@@ -1,18 +1,23 @@
 /**
  * @file error.ts
  * @brief TypeSea assertion error.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import { copyIssueArray } from "../issue/index.js";
 import { defineReadonlyProperty } from "./props.js";
 /**
- * @brief type sea assertion error.
- * @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 Error thrown by assert() after validation has already produced issues.
+ * @details The issue array is copied before publication so callers cannot mutate
+ * diagnostic state through the error object.
  */
 export class TypeSeaAssertionError extends Error {
     /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
+     * @brief Construct an assertion error from validation issues.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param issues Issues produced by checkSchema.
+     * @post Published issues are copied and exposed through a readonly property.
      */
     constructor(issues) {
         super("TypeSea assertion failed");

package/dist/guard/index.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public guard module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { BaseGuard } from "./base.js";
 export { TypeSeaAssertionError } from "./error.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EACV,KAAK,EACL,KAAK,EACL,aAAa,EACb,UAAU,EACV,KAAK,EACL,QAAQ,EACR,YAAY,EACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guard/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EACR,KAAK,EACL,KAAK,EACL,aAAa,EACb,UAAU,EACV,KAAK,EACL,QAAQ,EACR,YAAY,EACf,MAAM,YAAY,CAAC"}

package/dist/guard/index.js

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public guard module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { BaseGuard } from "./base.js";
 export { TypeSeaAssertionError } from "./error.js";

package/dist/guard/number.d.ts

@@ -1,32 +1,47 @@
 /**
  * @file number.ts
  * @brief Number guard implementation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import type { NumberSchema } from "../schema/index.js";
 import { BaseGuard } from "./base.js";
 import type { Presence } from "./types.js";
 /**
- * @brief number 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 finite number predicates.
+ * @details Bounds are normalized before entering the schema so the evaluator
+ * and compiler never have to defend against NaN or infinities later.
  */
 export declare class NumberGuard<TPresence extends Presence = "required"> extends BaseGuard<number, TPresence> {
     /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
+     * @brief Construct a frozen number guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param schema Number schema backing this guard.
      */
     constructor(schema: NumberSchema);
     /**
-     * @brief int.
-         */
+     * @brief Require finite numbers to be integers.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh NumberGuard with an appended integer check.
+     */
     int(): NumberGuard<TPresence>;
     /**
-     * @brief gte.
-           */
+     * @brief Add an inclusive lower bound.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Finite lower bound.
+     * @returns Fresh NumberGuard with an appended gte check.
+     */
     gte(value: number): NumberGuard<TPresence>;
     /**
-     * @brief lte.
-           */
+     * @brief Add an inclusive upper bound.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Finite upper bound.
+     * @returns Fresh NumberGuard with an appended lte check.
+     */
     lte(value: number): NumberGuard<TPresence>;
 }
 //# sourceMappingURL=number.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../../src/guard/number.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAMtC,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;;WAEO;IACA,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC;IAapC;;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;CAclD"}
+{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../../src/guard/number.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAMtC,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;;;;;OAKG;IACI,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC;IAapC;;;;;;OAMG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;IAmBjD;;;;;;OAMG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC;CAcpD"}

package/dist/guard/number.js

@@ -1,27 +1,34 @@
 /**
  * @file number.ts
  * @brief Number guard implementation.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
  */
 import { NumberCheckTag, SchemaTag } from "../kind/index.js";
 import { BaseGuard } from "./base.js";
 import { checkFiniteNumberBound, readNumberConstructorSchema, readNumberMethodSchema } from "./read.js";
 /**
- * @brief number 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 finite number predicates.
+ * @details Bounds are normalized before entering the schema so the evaluator
+ * and compiler never have to defend against NaN or infinities later.
  */
 export class NumberGuard extends BaseGuard {
     /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
+     * @brief Construct a frozen number guard.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param schema Number schema backing this guard.
      */
     constructor(schema) {
         super(readNumberConstructorSchema(schema));
         Object.freeze(this);
     }
     /**
-     * @brief int.
-         */
+     * @brief Require finite numbers to be integers.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @returns Fresh NumberGuard with an appended integer check.
+     */
     int() {
         const schema = readNumberMethodSchema(this, "number int receiver");
         return new NumberGuard({
@@ -35,11 +42,19 @@ export class NumberGuard extends BaseGuard {
         });
     }
     /**
-     * @brief gte.
-           */
+     * @brief Add an inclusive lower bound.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Finite lower bound.
+     * @returns Fresh NumberGuard with an appended gte check.
+     */
     gte(value) {
         const schema = readNumberMethodSchema(this, "number gte receiver");
         const bound = checkFiniteNumberBound(value, "gte");
+        /*
+         * Bounds are normalized before schema construction so interpreters and
+         * compilers never need to handle NaN or infinity inside hot validation.
+         */
         return new NumberGuard({
             tag: SchemaTag.Number,
             checks: [
@@ -52,8 +67,12 @@ export class NumberGuard extends BaseGuard {
         });
     }
     /**
-     * @brief lte.
-           */
+     * @brief Add an inclusive upper bound.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+     * @param value Finite upper bound.
+     * @returns Fresh NumberGuard with an appended lte check.
+     */
     lte(value) {
         const schema = readNumberMethodSchema(this, "number lte receiver");
         const bound = checkFiniteNumberBound(value, "lte");

package/dist/guard/props.d.ts

@@ -1,18 +1,42 @@
 /**
  * @file props.ts
  * @brief Guard object shape helpers.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ */
+/**
+ * @brief Define one immutable public property.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param target Object receiving the property.
+ * @param key Property key.
+ * @param value Stored property value.
+ * @param enumerable Whether the property should appear in enumeration.
+ * @post The property is non-configurable and non-writable.
  */
 export declare function defineReadonlyProperty(target: object, key: string, value: unknown, enumerable: boolean): void;
 /**
- * @brief is strict true.
+ * @brief Test for the only accepted refinement success value.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Predicate return value.
+ * @returns True only for the boolean literal true.
  */
 export declare function isStrictTrue(value: unknown): boolean;
 /**
- * @brief is record.
+ * @brief Test whether a value is a non-array object record.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Candidate runtime value.
+ * @returns True for object values that can carry string properties.
  */
 export declare function isRecord(value: unknown): value is Readonly<Record<string, unknown>>;
 /**
- * @brief is plain reg exp.
+ * @brief Accept only unmodified RegExp instances for schema storage.
+ * @details User-owned exec/test/source/flags overrides can change validation
+ * behavior after construction, so they are rejected at the API boundary.
+ * @param value Candidate pattern.
+ * @returns True for plain RegExp instances without own behavioral overrides.
  */
 export declare function isPlainRegExp(value: unknown): value is RegExp;
 //# sourceMappingURL=props.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../../src/guard/props.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,OAAO,GAClB,IAAI,CAON;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEnF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAO7D"}
+{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../../src/guard/props.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,OAAO,GACpB,IAAI,CAON;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEnF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAO7D"}

package/dist/guard/props.js

@@ -1,6 +1,18 @@
 /**
  * @file props.ts
  * @brief Guard object shape helpers.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ */
+/**
+ * @brief Define one immutable public property.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param target Object receiving the property.
+ * @param key Property key.
+ * @param value Stored property value.
+ * @param enumerable Whether the property should appear in enumeration.
+ * @post The property is non-configurable and non-writable.
  */
 export function defineReadonlyProperty(target, key, value, enumerable) {
     Object.defineProperty(target, key, {
@@ -11,19 +23,31 @@ export function defineReadonlyProperty(target, key, value, enumerable) {
     });
 }
 /**
- * @brief is strict true.
+ * @brief Test for the only accepted refinement success value.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Predicate return value.
+ * @returns True only for the boolean literal true.
  */
 export function isStrictTrue(value) {
     return value === true;
 }
 /**
- * @brief is record.
+ * @brief Test whether a value is a non-array object record.
+ * @details Guard helpers build new immutable schema wrappers so fluent APIs never mutate an
+ * existing guard instance.
+ * @param value Candidate runtime value.
+ * @returns True for object values that can carry string properties.
  */
 export function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * @brief is plain reg exp.
+ * @brief Accept only unmodified RegExp instances for schema storage.
+ * @details User-owned exec/test/source/flags overrides can change validation
+ * behavior after construction, so they are rejected at the API boundary.
+ * @param value Candidate pattern.
+ * @returns True for plain RegExp instances without own behavioral overrides.
  */
 export function isPlainRegExp(value) {
     return value instanceof RegExp &&