typesea 0.1.0 → 0.2.0

package/dist/evaluate/check-composite.js

@@ -1,18 +1,43 @@
 /**
  * @file check-composite.ts
  * @brief Composite diagnostic schema interpreters.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import { ObjectModeTag, PresenceTag, SchemaTag } from "../kind/index.js";
+import { schemaCanAcceptUndefined } from "../schema/index.js";
 import { pushIssue } from "./issue.js";
-import { actualType, findDiscriminatedUnionCase, hasObjectKey, isDataPropertyDescriptor, isPlainRecord, isStrictTrue, literalToExpected, readOwnDataProperty } from "./shared.js";
+import { actualType, findDiscriminatedUnionCase, hasObjectKey, isArrayIndexKey, isDataPropertyDescriptor, isPlainRecord, isStrictTrue, literalToExpected, readOwnDataProperty } from "./shared.js";
 /**
  * @brief collect array issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param item Schema applied to each logical array slot.
+ * @param value Candidate value supplied by the caller.
+ * @param path Mutable path stack reused by the diagnostic walker.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
+ * @post Every pushed path segment is popped before return.
  */
 export function collectArrayIssues(item, value, path, issues, state, collectChild) {
     if (!Array.isArray(value)) {
         pushIssue(path, issues, "expected_array", "array", actualType(value));
         return;
     }
+    if (schemaCanAcceptUndefined(item)) {
+        /*
+         * A sparse hole is observationally undefined for this item schema. Walking
+         * present descriptors keeps huge sparse inputs proportional to stored
+         * slots while preserving accessor rejection.
+         */
+        collectPresentArrayIssues(item, value, path, issues, state, collectChild);
+        return;
+    }
+    /*
+     * When undefined is not valid, each missing descriptor is a real validation
+     * failure. The length loop keeps diagnostics tied to the failing index.
+     */
     for (let index = 0; index < value.length; index += 1) {
         const itemProperty = readArrayIndexDataProperty(value, index);
         path.push(index);
@@ -25,8 +50,55 @@ export function collectArrayIssues(item, value, path, issues, state, collectChil
         path.pop();
     }
 }
+/**
+ * @brief collect present array issues.
+ * @details Holes are equivalent to `undefined` when the item schema accepts it,
+ * so only actual own index slots need descriptor checks and child validation.
+ * @param item Schema applied to each present own index.
+ * @param value Array already proven by the caller.
+ * @param path Mutable path stack reused by the diagnostic walker.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
+ * @post Non-index own properties are ignored to match normal array iteration.
+ */
+function collectPresentArrayIssues(item, value, path, issues, state, collectChild) {
+    const keys = Object.getOwnPropertyNames(value);
+    for (let keyIndex = 0; keyIndex < keys.length; keyIndex += 1) {
+        const key = keys[keyIndex];
+        if (key === undefined || !isArrayIndexKey(key, value.length)) {
+            continue;
+        }
+        /*
+         * Descriptor lookup is still mandatory on present indexes. It blocks
+         * getter-backed slots without invoking user code during validation.
+         */
+        const itemProperty = readArrayKeyDataProperty(value, key);
+        if (itemProperty === undefined) {
+            continue;
+        }
+        const index = Number(key);
+        path.push(index);
+        if (itemProperty === null) {
+            pushIssue(path, issues, "expected_array", "data property", "accessor");
+        }
+        else {
+            collectChild(item, itemProperty.value, path, issues, state);
+        }
+        path.pop();
+    }
+}
 /**
  * @brief collect tuple issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param items Tuple item schemas.
+ * @param value Candidate runtime value.
+ * @param path Mutable path stack reused by the diagnostic walker.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
+ * @post Every pushed tuple index is popped before return.
  */
 export function collectTupleIssues(items, value, path, issues, state, collectChild) {
     if (!Array.isArray(value)) {
@@ -37,6 +109,10 @@ export function collectTupleIssues(items, value, path, issues, state, collectChi
         pushIssue(path, issues, "expected_tuple_length", `length ${String(items.length)}`, `length ${String(value.length)}`);
     }
     const count = value.length < items.length ? value.length : items.length;
+    /*
+     * Length mismatch is reported once, then overlapping indexes are still
+     * diagnosed so callers get useful nested errors for present slots.
+     */
     for (let index = 0; index < count; index += 1) {
         const item = items[index];
         if (item === undefined) {
@@ -54,12 +130,25 @@ export function collectTupleIssues(items, value, path, issues, state, collectChi
     }
 }
 /**
- * @brief read array index data property.
+ * @brief Read one array index for diagnostic collection.
  * @details Reads an array element through its descriptor so validation does not execute getters.
+ * @param value Array being inspected.
+ * @param index Numeric array index.
  * @returns Data descriptor for elements, undefined for holes, and null for accessors.
  */
 function readArrayIndexDataProperty(value, index) {
-    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    return readArrayKeyDataProperty(value, String(index));
+}
+/**
+ * @brief Read one canonical array index key for diagnostic collection.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param value Array being inspected.
+ * @param key Canonical array index key.
+ * @returns Data descriptor for elements, undefined for holes, and null for accessors.
+ */
+function readArrayKeyDataProperty(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
     if (descriptor === undefined) {
         return undefined;
     }
@@ -70,6 +159,15 @@ function readArrayIndexDataProperty(value, index) {
 }
 /**
  * @brief collect record issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param item Schema applied to each own enumerable record value.
+ * @param value Candidate runtime value.
+ * @param path Mutable path stack reused by the diagnostic walker.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
+ * @post Every pushed record key is popped before return.
  */
 export function collectRecordIssues(item, value, path, issues, state, collectChild) {
     if (!isPlainRecord(value)) {
@@ -77,6 +175,10 @@ export function collectRecordIssues(item, value, path, issues, state, collectChi
         return;
     }
     const keys = Object.keys(value);
+    /*
+     * Records intentionally validate enumerable own string keys. Symbols and
+     * non-enumerable slots are outside record value semantics.
+     */
     for (let index = 0; index < keys.length; index += 1) {
         const key = keys[index];
         if (key === undefined) {
@@ -95,6 +197,15 @@ export function collectRecordIssues(item, value, path, issues, state, collectChi
 }
 /**
  * @brief collect object issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Object schema with entries and object mode.
+ * @param value Candidate runtime value.
+ * @param path Mutable path stack reused by the diagnostic walker.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
+ * @post Every pushed object key is popped before return.
  */
 export function collectObjectIssues(schema, value, path, issues, state, collectChild) {
     if (!isPlainRecord(value)) {
@@ -113,6 +224,11 @@ export function collectObjectIssues(schema, value, path, issues, state, collectC
         if (property === undefined) {
             if (entry.presence === PresenceTag.Optional &&
                 !Object.prototype.hasOwnProperty.call(record, entry.key)) {
+                /*
+                 * Missing optional key is valid. An own accessor at the same key
+                 * is not valid because readOwnDataProperty would have returned
+                 * undefined while hasOwnProperty remains true.
+                 */
                 path.pop();
                 continue;
             }
@@ -129,6 +245,10 @@ export function collectObjectIssues(schema, value, path, issues, state, collectC
         path.pop();
     }
     if (schema.mode === ObjectModeTag.Strict) {
+        /*
+         * Strict objects reject symbol and non-enumerable extras as well, so
+         * Reflect.ownKeys is required instead of Object.keys.
+         */
         const keys = Reflect.ownKeys(record);
         for (let index = 0; index < keys.length; index += 1) {
             const key = keys[index];
@@ -143,6 +263,15 @@ export function collectObjectIssues(schema, value, path, issues, state, collectC
 }
 /**
  * @brief collect discriminated union issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param key Discriminant property key.
+ * @param cases Closed discriminated union cases.
+ * @param value Candidate runtime value.
+ * @param path Mutable path stack reused by the diagnostic walker.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
  */
 export function collectDiscriminatedUnionIssues(key, cases, value, path, issues, state, collectChild) {
     if (!isPlainRecord(value)) {
@@ -151,6 +280,10 @@ export function collectDiscriminatedUnionIssues(key, cases, value, path, issues,
     }
     const discriminantProperty = readOwnDataProperty(value, key);
     if (discriminantProperty === undefined) {
+        /*
+         * The discriminant must be an own data property. Prototype values and
+         * accessors are rejected before branch selection.
+         */
         path.push(key);
         pushIssue(path, issues, "expected_discriminant", "data property", "missing or accessor");
         path.pop();
@@ -174,11 +307,26 @@ export function collectDiscriminatedUnionIssues(key, cases, value, path, issues,
 }
 /**
  * @brief collect refine issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param inner Schema validated before the predicate runs.
+ * @param predicate User predicate that must return true.
+ * @param name Refinement name used in diagnostics.
+ * @param value Candidate runtime value.
+ * @param path Mutable path stack reused by the diagnostic walker.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion and cycle state.
+ * @param collectChild Dispatcher for nested schema diagnostics.
  */
 export function collectRefineIssues(inner, predicate, name, value, path, issues, state, collectChild) {
     const before = issues.length;
     collectChild(inner, value, path, issues, state);
     if (issues.length === before && !isStrictTrue(predicate(value))) {
+        /*
+         * Refinement predicates run only after the inner schema produced no new
+         * issues. That keeps structural failures more specific than predicate
+         * failures.
+         */
         pushIssue(path, issues, "expected_refinement", name, actualType(value));
     }
 }

package/dist/evaluate/check-scalar.d.ts

@@ -1,18 +1,34 @@
 /**
  * @file check-scalar.ts
  * @brief Scalar diagnostic schema interpreters.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import { SchemaTag } from "../kind/index.js";
 import type { Issue, PathSegment } from "../issue/index.js";
 import { type Schema } from "../schema/index.js";
 /**
  * @brief collect string issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema String schema with scalar checks.
+ * @param value Candidate runtime value.
+ * @param path Current diagnostic path.
+ * @param issues Output issue buffer.
+ * @post Pattern checks reset lastIndex before testing.
  */
 export declare function collectStringIssues(schema: Extract<Schema, {
     readonly tag: typeof SchemaTag.String;
 }>, value: unknown, path: PathSegment[], issues: Issue[]): void;
 /**
  * @brief collect number issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Number schema with scalar checks.
+ * @param value Candidate runtime value.
+ * @param path Current diagnostic path.
+ * @param issues Output issue buffer.
+ * @post Bound checks run only after the finite-number guard succeeds.
  */
 export declare function collectNumberIssues(schema: Extract<Schema, {
     readonly tag: typeof SchemaTag.Number;

package/dist/evaluate/check-scalar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-scalar.d.ts","sourceRoot":"","sources":["../../src/evaluate/check-scalar.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEL,SAAS,EAEV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAEL,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAI5B;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,GACd,IAAI,CAgDN;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,GACd,IAAI,CAyCN"}
+{"version":3,"file":"check-scalar.d.ts","sourceRoot":"","sources":["../../src/evaluate/check-scalar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEH,SAAS,EAEZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAEH,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AAI5B;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,GAChB,IAAI,CA4DN;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,GAChB,IAAI,CA6CN"}

package/dist/evaluate/check-scalar.js

@@ -1,6 +1,8 @@
 /**
  * @file check-scalar.ts
  * @brief Scalar diagnostic schema interpreters.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import { NumberCheckTag, SchemaTag, StringCheckTag } from "../kind/index.js";
 import { UUID_PATTERN } from "../schema/index.js";
@@ -8,6 +10,13 @@ import { pushIssue } from "./issue.js";
 import { actualType } from "./shared.js";
 /**
  * @brief collect string issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema String schema with scalar checks.
+ * @param value Candidate runtime value.
+ * @param path Current diagnostic path.
+ * @param issues Output issue buffer.
+ * @post Pattern checks reset lastIndex before testing.
  */
 export function collectStringIssues(schema, value, path, issues) {
     if (typeof value !== "string") {
@@ -15,6 +24,10 @@ export function collectStringIssues(schema, value, path, issues) {
         return;
     }
     const checks = schema.checks;
+    /*
+     * Length and pattern checks only run after the type guard. That keeps
+     * diagnostics deterministic and avoids property reads on non-string values.
+     */
     for (let index = 0; index < checks.length; index += 1) {
         const check = checks[index];
         if (check === undefined) {
@@ -32,12 +45,20 @@ export function collectStringIssues(schema, value, path, issues) {
                 }
                 break;
             case StringCheckTag.Regex:
+                /*
+                 * User regexps may be global or sticky. Resetting lastIndex makes
+                 * repeated validation calls independent from prior tests.
+                 */
                 check.regex.lastIndex = 0;
                 if (!check.regex.test(value)) {
                     pushIssue(path, issues, "expected_pattern", check.name, "string");
                 }
                 break;
             case StringCheckTag.Uuid:
+                /*
+                 * UUID uses the shared library pattern but follows the same reset
+                 * discipline as user regexps.
+                 */
                 UUID_PATTERN.lastIndex = 0;
                 if (!UUID_PATTERN.test(value)) {
                     pushIssue(path, issues, "expected_pattern", "uuid", "string");
@@ -48,6 +69,13 @@ export function collectStringIssues(schema, value, path, issues) {
 }
 /**
  * @brief collect number issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Number schema with scalar checks.
+ * @param value Candidate runtime value.
+ * @param path Current diagnostic path.
+ * @param issues Output issue buffer.
+ * @post Bound checks run only after the finite-number guard succeeds.
  */
 export function collectNumberIssues(schema, value, path, issues) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -55,6 +83,10 @@ export function collectNumberIssues(schema, value, path, issues) {
         return;
     }
     const checks = schema.checks;
+    /*
+     * Integer and bound diagnostics are separated so invalid values report all
+     * failed number constraints after the base type has been proven.
+     */
     for (let index = 0; index < checks.length; index += 1) {
         const check = checks[index];
         if (check === undefined) {

package/dist/evaluate/check.d.ts

@@ -1,11 +1,18 @@
 /**
  * @file check.ts
  * @brief Diagnostic schema interpreter dispatcher.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import type { CheckResult } from "../issue/index.js";
 import { type Schema } from "../schema/index.js";
 /**
  * @brief check schema.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Schema used to validate the input.
+ * @param value Candidate runtime value.
+ * @returns Frozen success or diagnostic failure result.
  */
 export declare function checkSchema<TValue>(schema: Schema, value: unknown): CheckResult<TValue>;
 //# sourceMappingURL=check.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/evaluate/check.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,mBAAmB,CAAC;AAGzE,OAAO,EAEL,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AA0B5B;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,WAAW,CAAC,MAAM,CAAC,CAWrB"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/evaluate/check.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,mBAAmB,CAAC;AAGzE,OAAO,EAEH,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AA0B5B;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACf,WAAW,CAAC,MAAM,CAAC,CAmBrB"}

package/dist/evaluate/check.js

@@ -1,6 +1,8 @@
 /**
  * @file check.ts
  * @brief Diagnostic schema interpreter dispatcher.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import { SchemaTag } from "../kind/index.js";
 import { freezeIssueArray } from "../issue/index.js";
@@ -14,25 +16,51 @@ import { actualType, literalToExpected } from "./shared.js";
 import { enterValidation, leaveValidation, makeValidationState } from "./state.js";
 /**
  * @brief check schema.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Schema used to validate the input.
+ * @param value Candidate runtime value.
+ * @returns Frozen success or diagnostic failure result.
  */
 export function checkSchema(schema, value) {
     if (isSchemaWithState(schema, value, makeValidationState())) {
         return ok(value);
     }
+    /*
+     * The boolean predicate runs first to keep the valid path allocation-light.
+     * Diagnostics are collected only after failure, matching compiled check().
+     */
     const issues = [];
     const path = [];
     collectIssues(schema, value, path, issues, makeValidationState());
     if (issues.length === 0) {
+        /*
+         * Refine predicates can fail without emitting a structural issue. Add a
+         * conservative fallback so callers never receive an empty failure.
+         */
         pushIssue(path, issues, "expected_refinement", "matching schema", actualType(value));
     }
     return err(freezeIssueArray(issues));
 }
 /**
  * @brief collect issues.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Schema node being diagnosed.
+ * @param value Candidate runtime value.
+ * @param path Mutable path stack shared by recursive diagnostic calls.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion, cycle, and graph execution state.
+ * @post Calls `leaveValidation` only when `enterValidation` returned entered.
  */
 function collectIssues(schema, value, path, issues, state) {
     const entered = enterValidation(schema, value, state);
     if (entered === "cycle") {
+        /*
+         * A repeated schema/value pair means the recursive structure is already
+         * being validated higher on the stack. Treat it as provisionally valid
+         * to break cycles without fabricating duplicate diagnostics.
+         */
         return;
     }
     if (entered === "budget") {
@@ -44,6 +72,13 @@ function collectIssues(schema, value, path, issues, state) {
 }
 /**
  * @brief collect issues inner.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param schema Schema node being diagnosed after entry admission.
+ * @param value Candidate runtime value.
+ * @param path Mutable path stack shared by recursive diagnostic calls.
+ * @param issues Output issue buffer.
+ * @param state Shared recursion, cycle, and graph execution state.
  */
 function collectIssuesInner(schema, value, path, issues, state) {
     switch (schema.tag) {
@@ -96,6 +131,10 @@ function collectIssuesInner(schema, value, path, issues, state) {
             }
             return;
         case SchemaTag.Intersection:
+            /*
+             * Intersections accumulate diagnostics from both sides because both
+             * schemas must accept the same value.
+             */
             collectIssues(schema.left, value, path, issues, state);
             collectIssues(schema.right, value, path, issues, state);
             return;
@@ -117,6 +156,10 @@ function collectIssuesInner(schema, value, path, issues, state) {
             collectIssues(schema.inner, value, path, issues, state);
             return;
         case SchemaTag.Lazy:
+            /*
+             * Lazy schemas resolve through the shared state so recursive lazy
+             * references are tracked consistently with predicate evaluation.
+             */
             collectIssues(resolveLazySchema(schema, state.resolving), value, path, issues, state);
             return;
         case SchemaTag.Refine:

package/dist/evaluate/index.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public evaluation module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { checkSchema } from "./check.js";
 export { isSchema } from "./predicate.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/evaluate/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/evaluate/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/evaluate/index.js

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public evaluation module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { checkSchema } from "./check.js";
 export { isSchema } from "./predicate.js";

package/dist/evaluate/issue.d.ts

@@ -1,10 +1,20 @@
 /**
  * @file issue.ts
  * @brief Runtime validation issue construction.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import type { Issue, PathSegment } from "../issue/index.js";
 /**
- * @brief push issue.
+ * @brief Append one runtime validation issue.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param path Mutable path stack at the failing validation point.
+ * @param issues Output issue buffer.
+ * @param code Stable issue code.
+ * @param expected Human-readable expected value, when available.
+ * @param actual Human-readable actual value, when available.
+ * @post Stores a copied path so later stack mutation cannot alter the issue.
  */
 export declare function pushIssue(path: PathSegment[], issues: Issue[], code: Issue["code"], expected: string | undefined, actual: string | undefined): void;
 //# sourceMappingURL=issue.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../src/evaluate/issue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG5D;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EACnB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,IAAI,CAEN"}
+{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../src/evaluate/issue.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG5D;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACrB,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,EACnB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,GAC3B,IAAI,CAMN"}

package/dist/evaluate/issue.js

@@ -1,11 +1,25 @@
 /**
  * @file issue.ts
  * @brief Runtime validation issue construction.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
  */
 import { makeIssue } from "../issue/index.js";
 /**
- * @brief push issue.
+ * @brief Append one runtime validation issue.
+ * @details Interpreter helpers keep safe descriptor-based reads and diagnostic collection
+ * aligned with compiled behavior.
+ * @param path Mutable path stack at the failing validation point.
+ * @param issues Output issue buffer.
+ * @param code Stable issue code.
+ * @param expected Human-readable expected value, when available.
+ * @param actual Human-readable actual value, when available.
+ * @post Stores a copied path so later stack mutation cannot alter the issue.
  */
 export function pushIssue(path, issues, code, expected, actual) {
+    /*
+     * Diagnostic walkers reuse one path stack for speed. Copying here gives each
+     * issue immutable path semantics without forcing callers to allocate eagerly.
+     */
     issues.push(makeIssue(path.slice(), code, expected, actual, undefined));
 }

package/dist/evaluate/predicate.d.ts

@@ -1,25 +1,36 @@
 /**
  * @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 type { Schema } from "../schema/index.js";
 import type { ValidationState } from "./state.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 declare function isSchema(schema: Schema, value: unknown): boolean;
 /**
- * @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 declare function isSchemaWithState(schema: Schema, value: unknown, state: ValidationState): boolean;
 /**
- * @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 declare function isUnionSchema(options: readonly Schema[], value: unknown, state: ValidationState): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../../src/evaluate/predicate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,GACrB,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,GACrB,OAAO,CAST"}
+{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../../src/evaluate/predicate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,GACvB,OAAO,CAET;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CACzB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,GACvB,OAAO,CAaT"}