typesea 0.1.0 → 0.2.0

package/dist/evaluate/predicate.js

@@ -1,28 +1,39 @@
 /**
  * @file predicate.ts
  * @brief Compatibility entry points for IR-backed predicate execution.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import { executeSchemaPredicate, executeSchemaPredicateWithState } from "../plan/index.js";
 /**
- * @brief is schema.
- * @details Executes the schema through its optimized Sea-of-Nodes validation plan.
+ * @brief Execute a schema predicate through its optimized validation plan.
+ * @details This is the compatibility entry point used by guards that need a
+ * boolean answer without diagnostics.
+ * @param schema Schema used to validate the input.
+ * @param value Candidate runtime value.
  * @returns True when the input satisfies the schema.
  */
 export function isSchema(schema, value) {
     return executeSchemaPredicate(schema, value);
 }
 /**
- * @brief is schema with state.
+ * @brief Execute a schema predicate with caller-owned recursion state.
  * @details Shares recursion and cycle tracking with nested IR nodes.
- * @returns True when the input satisfies the schema under the borrowed state.
+ * @param schema Schema used to validate the input.
+ * @param value Candidate runtime value.
+ * @param state Validation state from an outer diagnostic or predicate run.
+ * @returns True when the input satisfies the schema under the shared state.
  */
 export function isSchemaWithState(schema, value, state) {
     return executeSchemaPredicateWithState(schema, value, state);
 }
 /**
- * @brief is union schema.
+ * @brief Execute union probing with shared recursion state.
  * @details Preserves the historical helper used by diagnostic generation while
  * routing each union option through IR-backed validation.
+ * @param options Union option schemas.
+ * @param value Candidate runtime value.
+ * @param state Validation state shared across option probes.
  * @returns True when at least one option accepts the value.
  */
 export function isUnionSchema(options, value, state) {
@@ -30,6 +41,10 @@ export function isUnionSchema(options, value, state) {
         const option = options[index];
         if (option !== undefined &&
             executeSchemaPredicateWithState(option, value, state)) {
+            /*
+             * Union diagnostics only need to know whether at least one branch
+             * accepts. Detailed branch diagnostics would allocate on a hot helper.
+             */
             return true;
         }
     }

package/dist/evaluate/shared.d.ts

@@ -1,59 +1,105 @@
 /**
  * @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 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,CAiBjD;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) {
@@ -74,7 +128,11 @@ export function actualType(value) {
     return typeof value;
 }
 /**
- * @brief literal to expected.
+ * @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/base.d.ts

@@ -1,72 +1,122 @@
 /**
  * @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 type { Graph } from "../ir/index.js";
 import type { Schema } from "../schema/index.js";
 import type { Brand, Guard, Infer, Presence, PresenceSymbol, RuntimeValue, TypeSymbol } from "./types.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 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 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.
-         */
+     * @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(): BaseGuard<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>>;
 }
 //# 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":"AAAA;;;;;GAKG;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,EACR,KAAK,EACL,KAAK,EACL,KAAK,EACL,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,UAAU,EACb,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,qBAAa,SAAS,CAClB,MAAM,EACN,SAAS,SAAS,QAAQ,GAAG,UAAU,CACzC,YAAW,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC;IACjC,SAAwB,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7C,SAAwB,CAAC,cAAc,CAAC,EAAE,SAAS,CAAC;IACpD,SAAwB,MAAM,EAAE,MAAM,CAAC;IAEvC;;;;;;OAMG;gBACgB,MAAM,EAAE,MAAM;IAYjC;;;;;;OAMG;IACI,EAAE,CACL,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACf,KAAK,IAAI,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;IAQ3C;;;;;;OAMG;IACI,KAAK,CACR,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACf,WAAW,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAO/C;;;;;;OAMG;IACI,MAAM,CACT,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACf,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC;IAUnD;;;;;OAKG;IACI,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK;IAIlC;;;;;OAKG;IACI,QAAQ,IAAI,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC;IAOhD;;;;;OAKG;IACI,aAAa,IAAI,SAAS,CAAC,MAAM,GAAG,SAAS,EAAE,SAAS,CAAC;IAOhE;;;;;OAKG;IACI,QAAQ,IAAI,SAAS,CAAC,MAAM,GAAG,IAAI,EAAE,SAAS,CAAC;IAOtD;;;;;OAKG;IACI,KAAK,IAAI,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;IAO5D;;;;;OAKG;IACI,KAAK,CAAC,MAAM,SAAS,MAAM,KAAK,SAAS,CAC5C,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,EACrB,SAAS,CACZ;IAQD;;;;;;;OAOG;IACI,MAAM,CACT,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,OAAO,EAC9D,IAAI,EAAE,MAAM,GACb,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC;IAe/B;;;;;;OAMG;IACI,EAAE,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC7C,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAY7D;;;;;;OAMG;IACI,SAAS,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACpD,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;CAOhE"}