typesea 0.1.0 → 0.3.0

package/dist/evaluate/shared.d.ts

@@ -1,59 +1,124 @@
 /**
  * @file shared.ts
  * @brief Shared scalar helpers for schema evaluation.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import type { DiscriminatedUnionCase, LiteralValue, ObjectKeyLookup, Schema } from "../schema/index.js";
 /**
- * @brief unknown record.
+ * @brief Object shape accepted by object and record validators.
+ * @details Values stay indexed by string keys only after the caller proves the
+ * input is not null and not an array.
  */
 export type UnknownRecord = Readonly<Record<string, unknown>>;
 /**
- * @brief data property descriptor.
- * @details Defines the subset of descriptors whose value is stable for one validation read.
+ * @brief Descriptor subset safe for validation reads.
+ * @details Only data descriptors are accepted because accessor descriptors can
+ * execute user code and can return different values across reads.
  * @invariant Accessor descriptors never match this contract.
  */
 export interface DataPropertyDescriptor {
     /**
-     * @brief value.
-     * @details The captured data slot is unknown until the schema-specific validator consumes it.
+     * @brief Captured property value.
+     * @details The value remains unknown until a schema-specific validator consumes it.
      * @invariant Accessing this field does not execute user getter code.
      */
     readonly value: unknown;
 }
 /**
- * @brief has object key.
+ * @brief Check membership in an object schema key lookup.
+ * @param keyLookup Null-prototype lookup generated by object schema construction.
+ * @param key Candidate own key.
+ * @returns True when the key belongs to the schema shape.
+ * @details The lookup is used instead of `in` so prototype pollution cannot make
+ * an undeclared key appear valid.
  */
 export declare function hasObjectKey(keyLookup: ObjectKeyLookup, key: string): boolean;
 /**
- * @brief read own data property.
+ * @brief Read one own data property from a runtime object.
  * @details Reads one own property through its descriptor so getters are not executed.
+ * @param record Plain object being validated.
+ * @param key Own key to inspect.
  * @returns Own data descriptor, or undefined for missing/accessor properties.
  */
 export declare function readOwnDataProperty(record: UnknownRecord, key: string): DataPropertyDescriptor | undefined;
 /**
- * @brief find discriminated union case.
+ * @brief Select a discriminated-union branch by its literal tag value.
+ * @details The case list is already builder-validated for unique literals, so a
+ * linear scan is enough for interpreter diagnostics while preserving declaration
+ * order and avoiding a per-schema map allocation.
+ * @param cases Closed discriminated union case list.
+ * @param value Discriminant string read from input.
+ * @returns Matching case schema, or undefined when the value is unknown.
  */
 export declare function findDiscriminatedUnionCase(cases: readonly DiscriminatedUnionCase[], value: string): Schema | undefined;
 /**
- * @brief is strict true.
+ * @brief Test for the only accepted refinement success value.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param value Predicate return value.
+ * @returns True only for the boolean literal true.
  */
 export declare function isStrictTrue(value: unknown): boolean;
 /**
- * @brief is plain record.
+ * @brief Test whether a value can host object-schema properties.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param value Candidate runtime value.
+ * @returns True for non-array object values.
  */
 export declare function isPlainRecord(value: unknown): value is UnknownRecord;
 /**
- * @brief is data property descriptor.
+ * @brief Test whether a descriptor carries a stable data slot.
  * @details Checks that a descriptor contains a data value instead of getter/setter code.
+ * @param descriptor Descriptor returned by Object.getOwnPropertyDescriptor.
  * @returns True when the descriptor has a stable value slot.
  */
 export declare function isDataPropertyDescriptor(descriptor: PropertyDescriptor): descriptor is DataPropertyDescriptor;
 /**
- * @brief actual type.
+ * @brief Test whether a property name is an in-bounds array index.
+ * @details Array validation ignores non-index own properties exactly as indexed
+ * loops do, but this helper lets sparse arrays avoid scanning every hole.
+ * @param key Own property name returned from an array object.
+ * @param length Current array length used as the upper bound.
+ * @returns True for canonical own array-index names below the current length.
+ * @invariant The result matches the indexes visited by a `0..length` loop.
+ */
+export declare function isArrayIndexKey(key: string, length: number): boolean;
+/**
+ * @brief Convert a runtime value into TypeSea's diagnostic type label.
+ * @details JavaScript reports null as object and NaN as number. Diagnostics use
+ * more precise labels so failure reports describe the actual value shape seen by
+ * validators.
+ * @param value Candidate runtime value.
+ * @returns Stable diagnostic type label.
  */
 export declare function actualType(value: unknown): string;
 /**
- * @brief literal to expected.
+ * @brief Validate a Date object without reading user-overridable methods.
+ * @param value Candidate runtime value.
+ * @returns True when value is a Date with a finite time value.
+ */
+export declare function isValidDateObject(value: unknown): value is Date;
+/**
+ * @brief Read a Date object's time value through the intrinsic method.
+ * @param value Date object already accepted by isValidDateObject.
+ * @returns Epoch millisecond value.
+ */
+export declare function readDateTime(value: Date): number;
+/**
+ * @brief Execute ordinary instanceof without invoking custom hasInstance hooks.
+ * @param value Candidate runtime value.
+ * @param constructor Constructor function stored in the schema.
+ * @returns True when the ordinary prototype-chain check accepts the value.
+ */
+export declare function ordinaryHasInstance(value: unknown, constructor: abstract new (...args: never[]) => unknown): boolean;
+/**
+ * @brief Render a literal schema value for the `expected` diagnostic field.
+ * @details String values are JSON-quoted and negative zero is preserved because
+ * both cases are otherwise easy to misread in generated messages.
+ * @param value Literal value from a schema.
+ * @returns Stable expected-value label for diagnostics.
  */
 export declare function literalToExpected(value: LiteralValue): string;
 //# sourceMappingURL=shared.d.ts.map

package/dist/evaluate/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/evaluate/shared.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,YAAY,EACZ,eAAe,EACf,MAAM,EACP,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IAErC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,MAAM,GACV,sBAAsB,GAAG,SAAS,CAMpC;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAQpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,kBAAkB,GAC7B,UAAU,IAAI,sBAAsB,CAEtC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiBjD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAiB7D"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/evaluate/shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACR,sBAAsB,EACtB,YAAY,EACZ,eAAe,EACf,MAAM,EACT,MAAM,oBAAoB,CAAC;AAI5B;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,MAAM,GACZ,sBAAsB,GAAG,SAAS,CAMpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACtC,KAAK,EAAE,SAAS,sBAAsB,EAAE,EACxC,KAAK,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,UAAU,EAAE,kBAAkB,GAC/B,UAAU,IAAI,sBAAsB,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAcpE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA0BjD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAG/D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GACxD,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAiB7D"}

package/dist/evaluate/shared.js

@@ -1,16 +1,26 @@
 /**
  * @file shared.ts
  * @brief Shared scalar helpers for schema evaluation.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
+const MAX_ARRAY_INDEX = 4_294_967_294;
 /**
- * @brief has object key.
+ * @brief Check membership in an object schema key lookup.
+ * @param keyLookup Null-prototype lookup generated by object schema construction.
+ * @param key Candidate own key.
+ * @returns True when the key belongs to the schema shape.
+ * @details The lookup is used instead of `in` so prototype pollution cannot make
+ * an undeclared key appear valid.
  */
 export function hasObjectKey(keyLookup, key) {
     return Object.prototype.hasOwnProperty.call(keyLookup, key);
 }
 /**
- * @brief read own data property.
+ * @brief Read one own data property from a runtime object.
  * @details Reads one own property through its descriptor so getters are not executed.
+ * @param record Plain object being validated.
+ * @param key Own key to inspect.
  * @returns Own data descriptor, or undefined for missing/accessor properties.
  */
 export function readOwnDataProperty(record, key) {
@@ -21,7 +31,13 @@ export function readOwnDataProperty(record, key) {
     return descriptor;
 }
 /**
- * @brief find discriminated union case.
+ * @brief Select a discriminated-union branch by its literal tag value.
+ * @details The case list is already builder-validated for unique literals, so a
+ * linear scan is enough for interpreter diagnostics while preserving declaration
+ * order and avoiding a per-schema map allocation.
+ * @param cases Closed discriminated union case list.
+ * @param value Discriminant string read from input.
+ * @returns Matching case schema, or undefined when the value is unknown.
  */
 export function findDiscriminatedUnionCase(cases, value) {
     for (let index = 0; index < cases.length; index += 1) {
@@ -33,27 +49,65 @@ export function findDiscriminatedUnionCase(cases, value) {
     return undefined;
 }
 /**
- * @brief is strict true.
+ * @brief Test for the only accepted refinement success value.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param value Predicate return value.
+ * @returns True only for the boolean literal true.
  */
 export function isStrictTrue(value) {
     return value === true;
 }
 /**
- * @brief is plain record.
+ * @brief Test whether a value can host object-schema properties.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param value Candidate runtime value.
+ * @returns True for non-array object values.
  */
 export function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * @brief is data property descriptor.
+ * @brief Test whether a descriptor carries a stable data slot.
  * @details Checks that a descriptor contains a data value instead of getter/setter code.
+ * @param descriptor Descriptor returned by Object.getOwnPropertyDescriptor.
  * @returns True when the descriptor has a stable value slot.
  */
 export function isDataPropertyDescriptor(descriptor) {
     return Object.prototype.hasOwnProperty.call(descriptor, "value");
 }
 /**
- * @brief actual type.
+ * @brief Test whether a property name is an in-bounds array index.
+ * @details Array validation ignores non-index own properties exactly as indexed
+ * loops do, but this helper lets sparse arrays avoid scanning every hole.
+ * @param key Own property name returned from an array object.
+ * @param length Current array length used as the upper bound.
+ * @returns True for canonical own array-index names below the current length.
+ * @invariant The result matches the indexes visited by a `0..length` loop.
+ */
+export function isArrayIndexKey(key, length) {
+    if (key.length === 0 || key === "length") {
+        return false;
+    }
+    /*
+     * Enumeration APIs expose array indexes as strings. Round-tripping through
+     * Number rejects aliases such as "01", floats, negative keys, and length.
+     */
+    const index = Number(key);
+    return Number.isInteger(index) &&
+        index >= 0 &&
+        index <= MAX_ARRAY_INDEX &&
+        index < length &&
+        String(index) === key;
+}
+/**
+ * @brief Convert a runtime value into TypeSea's diagnostic type label.
+ * @details JavaScript reports null as object and NaN as number. Diagnostics use
+ * more precise labels so failure reports describe the actual value shape seen by
+ * validators.
+ * @param value Candidate runtime value.
+ * @returns Stable diagnostic type label.
  */
 export function actualType(value) {
     if (value === null) {
@@ -62,6 +116,15 @@ export function actualType(value) {
     if (Array.isArray(value)) {
         return "array";
     }
+    if (value instanceof Date) {
+        return "date";
+    }
+    if (value instanceof Map) {
+        return "map";
+    }
+    if (value instanceof Set) {
+        return "set";
+    }
     if (typeof value === "bigint") {
         return "bigint";
     }
@@ -74,7 +137,37 @@ export function actualType(value) {
     return typeof value;
 }
 /**
- * @brief literal to expected.
+ * @brief Validate a Date object without reading user-overridable methods.
+ * @param value Candidate runtime value.
+ * @returns True when value is a Date with a finite time value.
+ */
+export function isValidDateObject(value) {
+    return value instanceof Date &&
+        Number.isFinite(Date.prototype.getTime.call(value));
+}
+/**
+ * @brief Read a Date object's time value through the intrinsic method.
+ * @param value Date object already accepted by isValidDateObject.
+ * @returns Epoch millisecond value.
+ */
+export function readDateTime(value) {
+    return Date.prototype.getTime.call(value);
+}
+/**
+ * @brief Execute ordinary instanceof without invoking custom hasInstance hooks.
+ * @param value Candidate runtime value.
+ * @param constructor Constructor function stored in the schema.
+ * @returns True when the ordinary prototype-chain check accepts the value.
+ */
+export function ordinaryHasInstance(value, constructor) {
+    return Function.prototype[Symbol.hasInstance].call(constructor, value);
+}
+/**
+ * @brief Render a literal schema value for the `expected` diagnostic field.
+ * @details String values are JSON-quoted and negative zero is preserved because
+ * both cases are otherwise easy to misread in generated messages.
+ * @param value Literal value from a schema.
+ * @returns Stable expected-value label for diagnostics.
  */
 export function literalToExpected(value) {
     if (value === null) {

package/dist/evaluate/state.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file state.ts
  * @brief Recursive validation state for cyclic input graphs.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import type { Schema } from "../schema/index.js";
 /**
@@ -11,6 +13,8 @@ import type { Schema } from "../schema/index.js";
 export type ValidationEnterResult = "entered" | "cycle" | "budget";
 /**
  * @brief default max validation depth.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  * @invariant The value stays below the V8 stack depth that recursive lazy schemas can exhaust.
  */
 export declare const DEFAULT_MAX_VALIDATION_DEPTH = 256;
@@ -26,40 +30,58 @@ export interface GraphEvaluationFrame {
 }
 /**
  * @brief validation state.
+ * @details Bundles recursion guards, lazy-resolution guards, and reusable graph
+ * frames so interpreter and IR execution observe the same limits.
  */
 export interface ValidationState {
     readonly active: WeakMap<object, WeakSet<Schema>>;
     readonly graphFrames: GraphEvaluationFrame[];
     readonly resolving: WeakSet<object>;
     /**
-     * @brief depth.
-     * @details Counts active recursive validator frames owned by this state object.
-     * @invariant The value is incremented only after budget admission and decremented by `leaveValidation`.
-     */
+   * @brief depth.
+   * @details Counts active recursive validator frames owned by this state object.
+   * @invariant The value is incremented only after budget admission and decremented by `leaveValidation`.
+   */
     depth: number;
     /**
-     * @brief graph depth.
-     * @details Counts active nested graph executions using `graphFrames` as a stack.
-     * @invariant Incremented by IR execution before frame use and decremented after it.
-     */
+   * @brief graph depth.
+   * @details Counts active nested graph executions using `graphFrames` as a stack.
+   * @invariant Incremented by IR execution before frame use and decremented after it.
+   */
     graphDepth: number;
     /**
-     * @brief max depth.
-     * @details Hard cap for recursive validator frames.
-     * @invariant Entering past this limit returns `budget` instead of recursing.
-     */
+   * @brief max depth.
+   * @details Hard cap for recursive validator frames.
+   * @invariant Entering past this limit returns `budget` instead of recursing.
+   */
     readonly maxDepth: number;
 }
 /**
- * @brief make validation state.
+ * @brief Allocate recursion and graph-frame state for one validation run.
+ * @returns Fresh validation state for one top-level validation operation.
+ * @details State is allocated per call so cycle tracking cannot leak between
+ * unrelated inputs.
  */
 export declare function makeValidationState(): ValidationState;
 /**
  * @brief enter validation.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Schema being entered.
+ * @param value Candidate runtime value.
+ * @param state Shared validation state.
+ * @returns Enter result describing cycle, budget, or admitted recursion.
+ * @post `state.depth` is incremented only for the entered result.
  */
 export declare function enterValidation(schema: Schema, value: unknown, state: ValidationState): ValidationEnterResult;
 /**
  * @brief leave validation.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Schema leaving validation.
+ * @param value Candidate runtime value.
+ * @param state Shared validation state.
+ * @post Reverses the depth and active-pair effects of `enterValidation`.
  */
 export declare function leaveValidation(schema: Schema, value: unknown, state: ValidationState): void;
 //# sourceMappingURL=state.d.ts.map

package/dist/evaluate/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/evaluate/state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC7B,SAAS,GACT,OAAO,GACP,QAAQ,CAAC;AAEb;;;GAGG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,WAAW,EAAE,oBAAoB,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,CASrD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,GACrB,qBAAqB,CAoBvB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,GACrB,IAAI,CAUN"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/evaluate/state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC3B,SAAS,GACT,OAAO,GACP,QAAQ,CAAC;AAEf;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,WAAW,EAAE,oBAAoB,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpC;;;;KAIC;IACD,KAAK,EAAE,MAAM,CAAC;IAEd;;;;KAIC;IACD,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;KAIC;IACD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,CASrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,GACvB,qBAAqB,CA6BvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,GACvB,IAAI,CAUN"}

package/dist/evaluate/state.js

@@ -1,14 +1,21 @@
 /**
  * @file state.ts
  * @brief Recursive validation state for cyclic input graphs.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 /**
  * @brief default max validation depth.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  * @invariant The value stays below the V8 stack depth that recursive lazy schemas can exhaust.
  */
 export const DEFAULT_MAX_VALIDATION_DEPTH = 256;
 /**
- * @brief make validation state.
+ * @brief Allocate recursion and graph-frame state for one validation run.
+ * @returns Fresh validation state for one top-level validation operation.
+ * @details State is allocated per call so cycle tracking cannot leak between
+ * unrelated inputs.
  */
 export function makeValidationState() {
     return {
@@ -22,10 +29,22 @@ export function makeValidationState() {
 }
 /**
  * @brief enter validation.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Schema being entered.
+ * @param value Candidate runtime value.
+ * @param state Shared validation state.
+ * @returns Enter result describing cycle, budget, or admitted recursion.
+ * @post `state.depth` is incremented only for the entered result.
  */
 export function enterValidation(schema, value, state) {
     const cached = isReferenceValue(value) ? state.active.get(value) : undefined;
     if (cached?.has(schema) === true) {
+        /*
+         * The same schema/value pair is already active. Returning cycle prevents
+         * infinite recursion on cyclic object graphs while preserving success for
+         * the already-open branch.
+         */
         return "cycle";
     }
     if (state.depth >= state.maxDepth) {
@@ -36,6 +55,10 @@ export function enterValidation(schema, value, state) {
         return "entered";
     }
     if (cached !== undefined) {
+        /*
+         * WeakSet membership is per object identity. Adding the schema marks this
+         * exact pair as active until leaveValidation removes it.
+         */
         cached.add(schema);
         return "entered";
     }
@@ -46,6 +69,12 @@ export function enterValidation(schema, value, state) {
 }
 /**
  * @brief leave validation.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Schema leaving validation.
+ * @param value Candidate runtime value.
+ * @param state Shared validation state.
+ * @post Reverses the depth and active-pair effects of `enterValidation`.
  */
 export function leaveValidation(schema, value, state) {
     if (!isReferenceValue(value)) {
@@ -59,7 +88,11 @@ export function leaveValidation(schema, value, state) {
     state.depth -= 1;
 }
 /**
- * @brief is reference value.
+ * @brief Test whether a value can participate in object graph cycles.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param value Candidate runtime value.
+ * @returns True for objects and functions that can participate in cycles.
  */
 function isReferenceValue(value) {
     return (typeof value === "object" && value !== null) || typeof value === "function";

package/dist/guard/array.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @file array.ts
+ * @brief Array guard implementation.
+ * @details Array helpers append immutable length constraints while preserving
+ * the item schema owned by the original guard.
+ */
+import type { ArraySchema } from "../schema/index.js";
+import { BaseGuard } from "./base.js";
+import type { Presence } from "./types.js";
+/**
+ * @brief Persistent builder for homogeneous array predicates.
+ * @details Length methods allocate a fresh schema record. The item schema is
+ * reused by identity because guard construction has already frozen it.
+ */
+export declare class ArrayGuard<TItem, TPresence extends Presence = "required"> extends BaseGuard<TItem[], TPresence> {
+    /**
+     * @brief Construct a frozen array guard.
+     * @param schema Array schema backing this guard.
+     * @post The receiver has no mutable instance state after construction.
+     */
+    constructor(schema: ArraySchema);
+    /**
+     * @brief Require an inclusive minimum array length.
+     * @param value Non-negative integer lower bound.
+     * @returns Fresh ArrayGuard with an appended minimum length check.
+     */
+    min(value: number): ArrayGuard<TItem, TPresence>;
+    /**
+     * @brief Require an inclusive maximum array length.
+     * @param value Non-negative integer upper bound.
+     * @returns Fresh ArrayGuard with an appended maximum length check.
+     */
+    max(value: number): ArrayGuard<TItem, TPresence>;
+    /**
+     * @brief Require one exact array length.
+     * @param value Non-negative integer exact length.
+     * @returns Fresh ArrayGuard with matching minimum and maximum length checks.
+     * @details Exact length is represented as two ordinary bounds so every
+     * backend can reuse the same comparison and diagnostic paths.
+     */
+    length(value: number): ArrayGuard<TItem, TPresence>;
+    /**
+     * @brief Require at least one array element.
+     * @returns Fresh ArrayGuard with a minimum length of one.
+     */
+    nonempty(): ArrayGuard<TItem, TPresence>;
+}
+//# sourceMappingURL=array.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/guard/array.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACH,SAAS,EAEZ,MAAM,WAAW,CAAC;AAMnB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,UAAU,CACnB,KAAK,EACL,SAAS,SAAS,QAAQ,GAAG,UAAU,CACzC,SAAQ,SAAS,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC;IAEnC;;;;OAIG;gBACgB,MAAM,EAAE,WAAW;IAKtC;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC;IAgBvD;;;;OAIG;IACI,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC;IAgBvD;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC;IAK1D;;;OAGG;IACI,QAAQ,IAAI,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC;CAGlD"}

package/dist/guard/array.js

@@ -0,0 +1,84 @@
+/**
+ * @file array.ts
+ * @brief Array guard implementation.
+ * @details Array helpers append immutable length constraints while preserving
+ * the item schema owned by the original guard.
+ */
+import { ArrayCheckTag, SchemaTag } from "../kind/index.js";
+import { BaseGuard, setArrayGuardFactory } from "./base.js";
+import { checkArrayLengthBound, readArrayConstructorSchema, readArrayMethodSchema } from "./read.js";
+/**
+ * @brief Persistent builder for homogeneous array predicates.
+ * @details Length methods allocate a fresh schema record. The item schema is
+ * reused by identity because guard construction has already frozen it.
+ */
+export class ArrayGuard extends BaseGuard {
+    /**
+     * @brief Construct a frozen array guard.
+     * @param schema Array schema backing this guard.
+     * @post The receiver has no mutable instance state after construction.
+     */
+    constructor(schema) {
+        super(readArrayConstructorSchema(schema));
+        Object.freeze(this);
+    }
+    /**
+     * @brief Require an inclusive minimum array length.
+     * @param value Non-negative integer lower bound.
+     * @returns Fresh ArrayGuard with an appended minimum length check.
+     */
+    min(value) {
+        const schema = readArrayMethodSchema(this, "array min receiver");
+        const bound = checkArrayLengthBound(value, "min");
+        return new ArrayGuard({
+            tag: SchemaTag.Array,
+            item: schema.item,
+            checks: [
+                ...schema.checks,
+                {
+                    tag: ArrayCheckTag.Min,
+                    value: bound
+                }
+            ]
+        });
+    }
+    /**
+     * @brief Require an inclusive maximum array length.
+     * @param value Non-negative integer upper bound.
+     * @returns Fresh ArrayGuard with an appended maximum length check.
+     */
+    max(value) {
+        const schema = readArrayMethodSchema(this, "array max receiver");
+        const bound = checkArrayLengthBound(value, "max");
+        return new ArrayGuard({
+            tag: SchemaTag.Array,
+            item: schema.item,
+            checks: [
+                ...schema.checks,
+                {
+                    tag: ArrayCheckTag.Max,
+                    value: bound
+                }
+            ]
+        });
+    }
+    /**
+     * @brief Require one exact array length.
+     * @param value Non-negative integer exact length.
+     * @returns Fresh ArrayGuard with matching minimum and maximum length checks.
+     * @details Exact length is represented as two ordinary bounds so every
+     * backend can reuse the same comparison and diagnostic paths.
+     */
+    length(value) {
+        const bound = checkArrayLengthBound(value, "exact");
+        return this.min(bound).max(bound);
+    }
+    /**
+     * @brief Require at least one array element.
+     * @returns Fresh ArrayGuard with a minimum length of one.
+     */
+    nonempty() {
+        return this.min(1);
+    }
+}
+setArrayGuardFactory((schema) => new ArrayGuard(schema));