typesea 0.1.0 → 0.3.0

package/dist/guard/base.d.ts

@@ -1,72 +1,152 @@
 /**
  * @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 type { CheckResult } from "../issue/index.js";
+import { SchemaTag } from "../kind/index.js";
+import { type CheckResult } from "../issue/index.js";
 import type { Graph } from "../ir/index.js";
 import type { Schema } from "../schema/index.js";
+import type { ArrayGuard } from "./array.js";
 import type { Brand, Guard, Infer, Presence, PresenceSymbol, RuntimeValue, TypeSymbol } from "./types.js";
+type ArraySchemaRecord = Extract<Schema, {
+    readonly tag: typeof SchemaTag.Array;
+}>;
+type ArrayGuardFactory = <TItem>(schema: ArraySchemaRecord) => ArrayGuard<TItem>;
 /**
- * @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 Register the concrete array guard factory.
+ * @param factory Constructor wrapper supplied by the array guard module.
+ * @details BaseGuard cannot import ArrayGuard directly without creating an
+ * initialization cycle. The guard barrel loads ArrayGuard, which installs this
+ * factory before public code can call fluent `array()`.
+ */
+export declare function setArrayGuardFactory(factory: ArrayGuardFactory): void;
+/**
+ * @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 declare class BaseGuard<TValue, TPresence extends Presence = "required"> implements Guard<TValue, TPresence> {
     readonly [TypeSymbol]: TValue;
     readonly [PresenceSymbol]: TPresence;
     readonly schema: Schema;
     /**
-     * @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: Schema);
     /**
-     * @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(this: unknown, value: unknown): value is RuntimeValue<TValue, TPresence>;
     /**
-     * @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(this: unknown, value: unknown): CheckResult<RuntimeValue<TValue, TPresence>>;
     /**
-     * @brief assert.
-             */
+     * @brief Validate a value and keep only the first diagnostic.
+ * @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 one frozen issue on failure.
+     */
+    checkFirst(this: unknown, value: unknown): CheckResult<RuntimeValue<TValue, TPresence>>;
+    /**
+     * @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(this: unknown, value: unknown): asserts value is RuntimeValue<TValue, TPresence>;
     /**
-     * @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(this: unknown): 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(): BaseGuard<TValue, "optional">;
     /**
-     * @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(): BaseGuard<TValue | undefined, TPresence>;
     /**
-     * @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(): BaseGuard<TValue | null, TPresence>;
     /**
-     * @brief array.
-         */
-    array(): BaseGuard<RuntimeValue<TValue, TPresence>[]>;
+     * @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(): ArrayGuard<RuntimeValue<TValue, TPresence>>;
     /**
-     * @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<TBrand extends string>(): BaseGuard<Brand<TValue, TBrand>, TPresence>;
     /**
-     * @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: (value: RuntimeValue<TValue, TPresence>) => boolean, name: string): BaseGuard<TValue, TPresence>;
     /**
-     * @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<TOther extends Guard<unknown, Presence>>(other: TOther): BaseGuard<RuntimeValue<TValue, TPresence> | Infer<TOther>>;
     /**
-     * @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<TOther extends Guard<unknown, Presence>>(other: TOther): BaseGuard<RuntimeValue<TValue, TPresence> & Infer<TOther>>;
+    /**
+     * @brief Require one own data property after this guard succeeds.
+     * @param key Own string property key to inspect.
+     * @param value Guard applied to the property value.
+     * @returns Fresh guard that preserves the base domain and property proof.
+     */
+    property<const TKey extends string, TGuard extends Guard<unknown, Presence>>(key: TKey, value: TGuard): BaseGuard<RuntimeValue<TValue, TPresence> & Readonly<Record<TKey, Infer<TGuard>>>>;
 }
+export {};
 //# sourceMappingURL=base.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/guard/base.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AASjD,OAAO,KAAK,EACV,KAAK,EACL,KAAK,EACL,KAAK,EACL,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,qBAAa,SAAS,CACpB,MAAM,EACN,SAAS,SAAS,QAAQ,GAAG,UAAU,CACvC,YAAW,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC;IACnC,SAAwB,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7C,SAAwB,CAAC,cAAc,CAAC,EAAE,SAAS,CAAC;IACpD,SAAwB,MAAM,EAAE,MAAM,CAAC;IAEvC;;;OAGG;gBACgB,MAAM,EAAE,MAAM;IAQjC;;eAEW;IACJ,EAAE,CACP,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;IAI3C;;eAEW;IACJ,KAAK,CACV,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,WAAW,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAO/C;;eAEW;IACJ,MAAM,CACX,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;IAUnD;;aAES;IACF,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK;IAIlC;;WAEO;IACA,QAAQ,IAAI,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC;IAOhD;;WAEO;IACA,aAAa,IAAI,SAAS,CAAC,MAAM,GAAG,SAAS,EAAE,SAAS,CAAC;IAOhE;;WAEO;IACA,QAAQ,IAAI,SAAS,CAAC,MAAM,GAAG,IAAI,EAAE,SAAS,CAAC;IAOtD;;WAEO;IACA,KAAK,IAAI,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;IAO5D;;WAEO;IACA,KAAK,CAAC,MAAM,SAAS,MAAM,KAAK,SAAS,CAC9C,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,EACrB,SAAS,CACV;IAQD;;eAEW;IACJ,MAAM,CACX,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,OAAO,EAC9D,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC;IAW/B;;aAES;IACF,EAAE,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC/C,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAY7D;;aAES;IACF,SAAS,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACtD,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;CAO9D"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/guard/base.ts"],"names":[],"mappings":"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"}

package/dist/guard/base.js

@@ -1,46 +1,100 @@
 /**
  * @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";
 import { makeValidationPlan } from "../plan/index.js";
+import { freezeIssueArray } from "../issue/index.js";
+import { err } from "../result/index.js";
 import { TypeSeaAssertionError } from "./error.js";
 import { checkRefinementInput, readConstructorSchema, readGuardSchema } from "./read.js";
 import { defineReadonlyProperty, isStrictTrue } from "./props.js";
 import { registerConstructedGuard } from "./registry.js";
+let arrayGuardFactory;
 /**
- * @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 Register the concrete array guard factory.
+ * @param factory Constructor wrapper supplied by the array guard module.
+ * @details BaseGuard cannot import ArrayGuard directly without creating an
+ * initialization cycle. The guard barrel loads ArrayGuard, which installs this
+ * factory before public code can call fluent `array()`.
+ */
+export function setArrayGuardFactory(factory) {
+    arrayGuardFactory = factory;
+}
+/**
+ * @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 keep only the first diagnostic.
+ * @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 one frozen issue on failure.
+     */
+    checkFirst(value) {
+        const result = checkSchema(readGuardSchema(this, "guard receiver"), value);
+        if (result.ok) {
+            return result;
+        }
+        return err(freezeIssueArray(readFirstIssue(result.error)));
+    }
+    /**
+     * @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 +102,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 +123,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 +135,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,17 +147,28 @@ 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({
+        const schema = {
             tag: SchemaTag.Array,
-            item: readGuardSchema(this, "array item")
-        });
+            item: readGuardSchema(this, "array item"),
+            checks: []
+        };
+        if (arrayGuardFactory === undefined) {
+            throw new TypeError("ArrayGuard factory is not initialized");
+        }
+        return arrayGuardFactory(schema);
     }
     /**
-     * @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 +177,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 +214,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,
@@ -133,4 +227,43 @@ export class BaseGuard {
             right: readGuardSchema(other, "intersection right")
         });
     }
+    /**
+     * @brief Require one own data property after this guard succeeds.
+     * @param key Own string property key to inspect.
+     * @param value Guard applied to the property value.
+     * @returns Fresh guard that preserves the base domain and property proof.
+     */
+    property(key, value) {
+        if (typeof key !== "string") {
+            throw new TypeError("property key must be a string");
+        }
+        return new BaseGuard({
+            tag: SchemaTag.Property,
+            base: readGuardSchema(this, "property base"),
+            key,
+            value: readGuardSchema(value, "property value")
+        });
+    }
+}
+/**
+ * @brief Copy the first issue into a single-slot diagnostic vector.
+ * @details The full checker owns the original frozen issue vector. checkFirst
+ * publishes a narrower vector so callers cannot observe or retain extra issues.
+ * @param issues Issue vector returned by the full checker.
+ * @returns Mutable vector containing zero or one copied issue.
+ */
+function readFirstIssue(issues) {
+    const first = issues[0];
+    if (first === undefined) {
+        return [];
+    }
+    return [
+        {
+            path: first.path.slice(),
+            code: first.code,
+            expected: first.expected,
+            actual: first.actual,
+            message: first.message
+        }
+    ];
 }

package/dist/guard/date.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file date.ts
+ * @brief Date guard implementation.
+ * @details Date helpers store normalized epoch-millisecond bounds so runtime
+ * validation never has to read caller-owned Date objects again.
+ */
+import type { DateSchema } from "../schema/index.js";
+import { BaseGuard } from "./base.js";
+import type { Presence } from "./types.js";
+/**
+ * @brief Persistent builder for valid Date predicates.
+ * @details Bound methods allocate fresh schema records and keep the source guard
+ * immutable, matching the scalar guard discipline used by number and string.
+ */
+export declare class DateGuard<TPresence extends Presence = "required"> extends BaseGuard<Date, TPresence> {
+    /**
+     * @brief Construct a frozen Date guard.
+     * @param schema Date schema backing this guard.
+     */
+    constructor(schema: DateSchema);
+    /**
+     * @brief Add an inclusive lower Date bound.
+     * @param value Valid Date object used as the lower bound.
+     * @returns Fresh DateGuard with an appended min check.
+     */
+    min(value: Date): DateGuard<TPresence>;
+    /**
+     * @brief Add an inclusive upper Date bound.
+     * @param value Valid Date object used as the upper bound.
+     * @returns Fresh DateGuard with an appended max check.
+     */
+    max(value: Date): DateGuard<TPresence>;
+}
+//# sourceMappingURL=date.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../../src/guard/date.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAMtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,SAAS,CAClB,SAAS,SAAS,QAAQ,GAAG,UAAU,CACzC,SAAQ,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC;IAEhC;;;OAGG;gBACgB,MAAM,EAAE,UAAU;IAKrC;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC;IAc7C;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC;CAahD"}

package/dist/guard/date.js

@@ -0,0 +1,60 @@
+/**
+ * @file date.ts
+ * @brief Date guard implementation.
+ * @details Date helpers store normalized epoch-millisecond bounds so runtime
+ * validation never has to read caller-owned Date objects again.
+ */
+import { DateCheckTag, SchemaTag } from "../kind/index.js";
+import { BaseGuard } from "./base.js";
+import { checkDateBound, readDateConstructorSchema, readDateMethodSchema } from "./read.js";
+/**
+ * @brief Persistent builder for valid Date predicates.
+ * @details Bound methods allocate fresh schema records and keep the source guard
+ * immutable, matching the scalar guard discipline used by number and string.
+ */
+export class DateGuard extends BaseGuard {
+    /**
+     * @brief Construct a frozen Date guard.
+     * @param schema Date schema backing this guard.
+     */
+    constructor(schema) {
+        super(readDateConstructorSchema(schema));
+        Object.freeze(this);
+    }
+    /**
+     * @brief Add an inclusive lower Date bound.
+     * @param value Valid Date object used as the lower bound.
+     * @returns Fresh DateGuard with an appended min check.
+     */
+    min(value) {
+        const schema = readDateMethodSchema(this, "date min receiver");
+        return new DateGuard({
+            tag: SchemaTag.Date,
+            checks: [
+                ...schema.checks,
+                {
+                    tag: DateCheckTag.Min,
+                    value: checkDateBound(value, "min")
+                }
+            ]
+        });
+    }
+    /**
+     * @brief Add an inclusive upper Date bound.
+     * @param value Valid Date object used as the upper bound.
+     * @returns Fresh DateGuard with an appended max check.
+     */
+    max(value) {
+        const schema = readDateMethodSchema(this, "date max receiver");
+        return new DateGuard({
+            tag: SchemaTag.Date,
+            checks: [
+                ...schema.checks,
+                {
+                    tag: DateCheckTag.Max,
+                    value: checkDateBound(value, "max")
+                }
+            ]
+        });
+    }
+}

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");