typesea 0.1.0 → 0.3.0

package/dist/evaluate/check-scalar.js

@@ -1,13 +1,22 @@
 /**
  * @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";
+import { DateCheckTag, NumberCheckTag, SchemaTag, StringCheckTag } from "../kind/index.js";
+import { EMAIL_PATTERN, IPV4_PATTERN, IPV6_PATTERN, ISO_DATETIME_PATTERN, ISO_DATE_PATTERN, ULID_PATTERN, URL_PATTERN, UUID_PATTERN } from "../schema/index.js";
 import { pushIssue } from "./issue.js";
-import { actualType } from "./shared.js";
+import { actualType, isValidDateObject, readDateTime } 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,22 +45,111 @@ 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");
                 }
                 break;
+            case StringCheckTag.Email:
+                EMAIL_PATTERN.lastIndex = 0;
+                if (!EMAIL_PATTERN.test(value)) {
+                    pushIssue(path, issues, "expected_pattern", "email", "string");
+                }
+                break;
+            case StringCheckTag.Url:
+                URL_PATTERN.lastIndex = 0;
+                if (!URL_PATTERN.test(value)) {
+                    pushIssue(path, issues, "expected_pattern", "url", "string");
+                }
+                break;
+            case StringCheckTag.IsoDate:
+                ISO_DATE_PATTERN.lastIndex = 0;
+                if (!ISO_DATE_PATTERN.test(value)) {
+                    pushIssue(path, issues, "expected_pattern", "iso_date", "string");
+                }
+                break;
+            case StringCheckTag.IsoDateTime:
+                ISO_DATETIME_PATTERN.lastIndex = 0;
+                if (!ISO_DATETIME_PATTERN.test(value)) {
+                    pushIssue(path, issues, "expected_pattern", "iso_datetime", "string");
+                }
+                break;
+            case StringCheckTag.Ulid:
+                ULID_PATTERN.lastIndex = 0;
+                if (!ULID_PATTERN.test(value)) {
+                    pushIssue(path, issues, "expected_pattern", "ulid", "string");
+                }
+                break;
+            case StringCheckTag.Ipv4:
+                IPV4_PATTERN.lastIndex = 0;
+                if (!IPV4_PATTERN.test(value)) {
+                    pushIssue(path, issues, "expected_pattern", "ipv4", "string");
+                }
+                break;
+            case StringCheckTag.Ipv6:
+                IPV6_PATTERN.lastIndex = 0;
+                if (!IPV6_PATTERN.test(value)) {
+                    pushIssue(path, issues, "expected_pattern", "ipv6", "string");
+                }
+                break;
+        }
+    }
+}
+/**
+ * @brief Collect Date issues.
+ * @param value Candidate runtime value.
+ * @param path Current diagnostic path.
+ * @param issues Output issue buffer.
+ */
+export function collectDateIssues(schema, value, path, issues) {
+    if (!isValidDateObject(value)) {
+        pushIssue(path, issues, "expected_date", "valid Date", actualType(value));
+        return;
+    }
+    const time = readDateTime(value);
+    const checks = schema.checks;
+    for (let index = 0; index < checks.length; index += 1) {
+        const check = checks[index];
+        if (check === undefined) {
+            continue;
+        }
+        switch (check.tag) {
+            case DateCheckTag.Min:
+                if (time < check.value) {
+                    pushIssue(path, issues, "expected_gte", `>= ${new Date(check.value).toISOString()}`, new Date(time).toISOString());
+                }
+                break;
+            case DateCheckTag.Max:
+                if (time > check.value) {
+                    pushIssue(path, issues, "expected_lte", `<= ${new Date(check.value).toISOString()}`, new Date(time).toISOString());
+                }
+                break;
         }
     }
 }
 /**
  * @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 +157,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) {
@@ -76,6 +182,21 @@ export function collectNumberIssues(schema, value, path, issues) {
                     pushIssue(path, issues, "expected_lte", `<= ${String(check.value)}`, String(value));
                 }
                 break;
+            case NumberCheckTag.Gt:
+                if (value <= check.value) {
+                    pushIssue(path, issues, "expected_gt", `> ${String(check.value)}`, String(value));
+                }
+                break;
+            case NumberCheckTag.Lt:
+                if (value >= check.value) {
+                    pushIssue(path, issues, "expected_lt", `< ${String(check.value)}`, String(value));
+                }
+                break;
+            case NumberCheckTag.MultipleOf:
+                if (value % check.value !== 0) {
+                    pushIssue(path, issues, "expected_multiple_of", `multiple of ${String(check.value)}`, String(value));
+                }
+                break;
         }
     }
 }

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;AA+B5B;;;;;;;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,38 +1,66 @@
 /**
  * @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";
 import { err, ok } from "../result/index.js";
 import { resolveLazySchema } from "../schema/index.js";
-import { collectArrayIssues, collectDiscriminatedUnionIssues, collectObjectIssues, collectRecordIssues, collectRefineIssues, collectTupleIssues } from "./check-composite.js";
-import { collectNumberIssues, collectStringIssues } from "./check-scalar.js";
+import { collectArrayIssues, collectDiscriminatedUnionIssues, collectInstanceOfIssues, collectMapIssues, collectObjectIssues, collectPropertyIssues, collectRecordIssues, collectRefineIssues, collectSetIssues, collectTupleIssues } from "./check-composite.js";
+import { collectDateIssues, collectNumberIssues, collectStringIssues } from "./check-scalar.js";
 import { pushIssue } from "./issue.js";
 import { isSchemaWithState, isUnionSchema } from "./predicate.js";
 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) {
@@ -58,6 +93,9 @@ function collectIssuesInner(schema, value, path, issues, state) {
         case SchemaTag.Number:
             collectNumberIssues(schema, value, path, issues);
             return;
+        case SchemaTag.Date:
+            collectDateIssues(schema, value, path, issues);
+            return;
         case SchemaTag.BigInt:
             if (typeof value !== "bigint") {
                 pushIssue(path, issues, "expected_bigint", "bigint", actualType(value));
@@ -79,14 +117,26 @@ function collectIssuesInner(schema, value, path, issues, state) {
             }
             return;
         case SchemaTag.Array:
-            collectArrayIssues(schema.item, value, path, issues, state, collectIssues);
+            collectArrayIssues(schema, value, path, issues, state, collectIssues);
             return;
         case SchemaTag.Tuple:
-            collectTupleIssues(schema.items, value, path, issues, state, collectIssues);
+            collectTupleIssues(schema, value, path, issues, state, collectIssues);
             return;
         case SchemaTag.Record:
             collectRecordIssues(schema.value, value, path, issues, state, collectIssues);
             return;
+        case SchemaTag.Map:
+            collectMapIssues(schema, value, path, issues, state, collectIssues);
+            return;
+        case SchemaTag.Set:
+            collectSetIssues(schema, value, path, issues, state, collectIssues);
+            return;
+        case SchemaTag.InstanceOf:
+            collectInstanceOfIssues(schema, value, path, issues);
+            return;
+        case SchemaTag.Property:
+            collectPropertyIssues(schema, value, path, issues, state, collectIssues);
+            return;
         case SchemaTag.Object:
             collectObjectIssues(schema, value, path, issues, state, collectIssues);
             return;
@@ -96,6 +146,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 +171,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"}

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;
         }
     }