typesea 0.1.0 → 0.2.0

package/dist/plan/predicate.js

@@ -1,9 +1,12 @@
 /**
  * @file predicate.ts
  * @brief Sea-of-Nodes predicate executor.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
-import { NodeTag, SchemaTag } from "../kind/index.js";
-import { resolveLazySchema } from "../schema/index.js";
+import { NodeTag, ObjectModeTag, PresenceTag, SchemaTag } from "../kind/index.js";
+import { resolveLazySchema, schemaCanAcceptUndefined } from "../schema/index.js";
+import { isArrayIndexKey } from "../evaluate/shared.js";
 import { enterValidation, leaveValidation, makeValidationState } from "../evaluate/state.js";
 import { makeValidationPlan, schemaRequiresTracking } from "./cache.js";
 import { executeSchemaKernel } from "./schema-predicate.js";
@@ -49,6 +52,8 @@ export function executeGraphPredicate(graph, value, state) {
 }
 /**
  * @brief execute schema predicate inner.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function executeSchemaPredicateInner(schema, value, state) {
     switch (schema.tag) {
@@ -65,6 +70,8 @@ function executeSchemaPredicateInner(schema, value, state) {
 }
 /**
  * @brief evaluate node.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function evaluateNode(graph, id, input, values, seen, epoch, state) {
     if (seen[id] === epoch) {
@@ -80,6 +87,8 @@ function evaluateNode(graph, id, input, values, seen, epoch, state) {
 }
 /**
  * @brief evaluate graph node.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function evaluateGraphNode(graph, node, input, values, seen, epoch, state) {
     switch (node.tag) {
@@ -132,13 +141,19 @@ function evaluateGraphNode(graph, node, input, values, seen, epoch, state) {
         case NodeTag.StrictKeys:
             return testStrictKeys(evaluateNode(graph, node.object, input, values, seen, epoch, state), node.keys);
         case NodeTag.ArrayEvery:
-            return testArrayEvery(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.item, state);
+            return testArrayEvery(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.item, node.itemGraph, state);
         case NodeTag.TupleItems:
-            return testTupleItems(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.items, state);
+            return testTupleItems(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.itemGraphs, state);
         case NodeTag.RecordEvery:
-            return testRecordEvery(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.item, state);
+            return testRecordEvery(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.itemGraph, state);
         case NodeTag.DiscriminantDispatch:
-            return testDiscriminantDispatch(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.key, node.schemas, node.lookup, state);
+            return testDiscriminantDispatch(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.key, node.graphs, node.lookup, state);
+        case NodeTag.ObjectShape:
+            return testObjectShape(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.entries, node.keys, node.mode, node.allRequired, state);
+        case NodeTag.UnionDispatch:
+            return testUnionDispatch(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.graphs, node.masks, state);
+        case NodeTag.PrimitiveUnion:
+            return testUnionDispatch(evaluateNode(graph, node.value, input, values, seen, epoch, state), node.graphs, node.masks, state);
         case NodeTag.SchemaCheck:
             return executeSchemaPredicateWithState(node.schema, evaluateNode(graph, node.value, input, values, seen, epoch, state), state);
         case NodeTag.And:
@@ -151,6 +166,8 @@ function evaluateGraphNode(graph, node, input, values, seen, epoch, state) {
 }
 /**
  * @brief evaluate and.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function evaluateAnd(graph, ids, input, values, seen, epoch, state) {
     for (let index = 0; index < ids.length; index += 1) {
@@ -164,6 +181,8 @@ function evaluateAnd(graph, ids, input, values, seen, epoch, state) {
 }
 /**
  * @brief evaluate or.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function evaluateOr(graph, ids, input, values, seen, epoch, state) {
     for (let index = 0; index < ids.length; index += 1) {
@@ -177,15 +196,58 @@ function evaluateOr(graph, ids, input, values, seen, epoch, state) {
 }
 /**
  * @brief test array every.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Candidate value supplied to the graph executor.
+ * @param item Source schema retained by the ArrayEvery node.
+ * @param itemGraph Optimized graph used for each validated slot.
+ * @param state Shared recursion and cycle state.
+ * @returns True when every relevant slot satisfies `itemGraph`.
  */
-function testArrayEvery(value, item, state) {
+function testArrayEvery(value, item, itemGraph, state) {
     if (!Array.isArray(value)) {
         return false;
     }
+    if (schemaCanAcceptUndefined(item)) {
+        /*
+         * The graph alone cannot reveal whether holes are valid. The retained
+         * schema decides that question, then the graph validates only present
+         * own indexes.
+         */
+        return testPresentArrayIndexes(value, itemGraph, state);
+    }
     for (let index = 0; index < value.length; index += 1) {
         const slot = readArrayIndexValue(value, index);
         if (slot.accessor ||
-            !executeSchemaPredicateWithState(item, slot.value, state)) {
+            !executeGraphPredicate(itemGraph, slot.value, state)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * @brief test present array indexes.
+ * @details Holes are skipped only after the caller proved that undefined passes
+ * the item schema, preserving sparse-array semantics without scanning every hole.
+ * @param value Array already proven by the caller.
+ * @param itemGraph Optimized graph used for each present index.
+ * @param state Shared recursion and cycle state.
+ * @returns True when every present own index satisfies `itemGraph`.
+ */
+function testPresentArrayIndexes(value, itemGraph, state) {
+    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;
+        }
+        /*
+         * Present descriptors still need the safe read path. Accessors fail
+         * before their getter can observe validation.
+         */
+        const slot = readArrayKeyValue(value, key);
+        if (slot.accessor ||
+            (slot.present && !executeGraphPredicate(itemGraph, slot.value, state))) {
             return false;
         }
     }
@@ -193,19 +255,21 @@ function testArrayEvery(value, item, state) {
 }
 /**
  * @brief test tuple items.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
-function testTupleItems(value, items, state) {
-    if (!Array.isArray(value) || value.length !== items.length) {
+function testTupleItems(value, itemGraphs, state) {
+    if (!Array.isArray(value) || value.length !== itemGraphs.length) {
         return false;
     }
-    for (let index = 0; index < items.length; index += 1) {
-        const item = items[index];
-        if (item === undefined) {
+    for (let index = 0; index < itemGraphs.length; index += 1) {
+        const itemGraph = itemGraphs[index];
+        if (itemGraph === undefined) {
             return false;
         }
         const slot = readArrayIndexValue(value, index);
         if (slot.accessor ||
-            !executeSchemaPredicateWithState(item, slot.value, state)) {
+            !executeGraphPredicate(itemGraph, slot.value, state)) {
             return false;
         }
     }
@@ -213,8 +277,10 @@ function testTupleItems(value, items, state) {
 }
 /**
  * @brief test record every.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
-function testRecordEvery(value, item, state) {
+function testRecordEvery(value, itemGraph, state) {
     if (!isPlainRecord(value)) {
         return false;
     }
@@ -227,7 +293,7 @@ function testRecordEvery(value, item, state) {
         const descriptor = Object.getOwnPropertyDescriptor(value, key);
         if (descriptor === undefined ||
             !Object.prototype.hasOwnProperty.call(descriptor, "value") ||
-            !executeSchemaPredicateWithState(item, descriptor.value, state)) {
+            !executeGraphPredicate(itemGraph, descriptor.value, state)) {
             return false;
         }
     }
@@ -235,8 +301,10 @@ function testRecordEvery(value, item, state) {
 }
 /**
  * @brief test discriminant dispatch.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
-function testDiscriminantDispatch(value, key, schemas, lookup, state) {
+function testDiscriminantDispatch(value, key, graphs, lookup, state) {
     if (!isPlainRecord(value)) {
         return false;
     }
@@ -252,34 +320,170 @@ function testDiscriminantDispatch(value, key, schemas, lookup, state) {
     if (index === undefined) {
         return false;
     }
-    const schema = schemas[index];
-    return schema !== undefined &&
-        executeSchemaPredicateWithState(schema, value, state);
+    const graph = graphs[index];
+    return graph !== undefined && executeGraphPredicate(graph, value, state);
 }
 /**
- * @brief read array index value.
+ * @brief test object shape.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ */
+function testObjectShape(value, entries, keys, mode, allRequired, state) {
+    if (!isPlainRecord(value)) {
+        return false;
+    }
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (entry === undefined) {
+            return false;
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, entry.key);
+        if (descriptor === undefined) {
+            if (entry.presence === PresenceTag.Optional &&
+                !Object.prototype.hasOwnProperty.call(value, entry.key)) {
+                continue;
+            }
+            return false;
+        }
+        if (!Object.prototype.hasOwnProperty.call(descriptor, "value") ||
+            !executeGraphPredicate(entry.graph, descriptor.value, state)) {
+            return false;
+        }
+    }
+    if (mode !== ObjectModeTag.Strict) {
+        return true;
+    }
+    if (allRequired) {
+        return Object.getOwnPropertyNames(value).length === entries.length &&
+            Object.getOwnPropertySymbols(value).length === 0;
+    }
+    const present = Reflect.ownKeys(value);
+    for (let index = 0; index < present.length; index += 1) {
+        const key = present[index];
+        if (typeof key !== "string" || !keys.includes(key)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * @brief union mask.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ */
+const UnionMask = {
+    String: 1 << 0,
+    Number: 1 << 1,
+    Boolean: 1 << 2,
+    BigInt: 1 << 3,
+    Symbol: 1 << 4,
+    Undefined: 1 << 5,
+    Null: 1 << 6,
+    Array: 1 << 7,
+    Object: 1 << 8,
+    Function: 1 << 9,
+    Any: (1 << 10) - 1
+};
+/**
+ * @brief test union dispatch.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ */
+function testUnionDispatch(value, graphs, masks, state) {
+    const valueMask = valueUnionMask(value);
+    for (let index = 0; index < graphs.length; index += 1) {
+        const graph = graphs[index];
+        const mask = masks[index];
+        if (graph !== undefined &&
+            mask !== undefined &&
+            (mask & valueMask) !== 0 &&
+            executeGraphPredicate(graph, value, state)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * @brief value union mask.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ */
+function valueUnionMask(value) {
+    if (value === null) {
+        return UnionMask.Null;
+    }
+    if (Array.isArray(value)) {
+        return UnionMask.Array;
+    }
+    switch (typeof value) {
+        case "string":
+            return UnionMask.String;
+        case "number":
+            return UnionMask.Number;
+        case "boolean":
+            return UnionMask.Boolean;
+        case "bigint":
+            return UnionMask.BigInt;
+        case "symbol":
+            return UnionMask.Symbol;
+        case "undefined":
+            return UnionMask.Undefined;
+        case "object":
+            return UnionMask.Object;
+        case "function":
+            return UnionMask.Function;
+        default:
+            return UnionMask.Any;
+    }
+}
+/**
+ * @brief Read one array index for graph predicate execution.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Array being inspected.
+ * @param index Numeric index.
+ * @returns Descriptor-derived slot record including accessor status.
  */
 function readArrayIndexValue(value, index) {
-    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    return readArrayKeyValue(value, String(index));
+}
+/**
+ * @brief Read one canonical array index key without invoking accessors.
+ * @param value Array being inspected.
+ * @param key Canonical array index key.
+ * @returns Slot record distinguishing holes, data slots, and accessor slots.
+ * @details Graph predicates must preserve safe-mode behavior, so an accessor is
+ * reported as present but unreadable instead of being invoked.
+ */
+function readArrayKeyValue(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
     if (descriptor === undefined) {
         return {
             accessor: false,
+            present: false,
             value: undefined
         };
     }
     if (!Object.prototype.hasOwnProperty.call(descriptor, "value")) {
         return {
             accessor: true,
+            present: true,
             value: undefined
         };
     }
     return {
         accessor: false,
+        present: true,
         value: descriptor.value
     };
 }
 /**
- * @brief read own data value.
+ * @brief Read one own data property from an object or function host.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Candidate property host.
+ * @param key Property key to inspect.
+ * @returns Stored value, or undefined when absent or accessor-backed.
  */
 function readOwnDataValue(value, key) {
     if (!isPropertyHost(value)) {
@@ -293,14 +497,24 @@ function readOwnDataValue(value, key) {
     return descriptor.value;
 }
 /**
- * @brief has own property.
+ * @brief Test whether a value owns a property without reading it.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Candidate property host.
+ * @param key Property key to inspect.
+ * @returns True when the key exists directly on the value.
  */
 function hasOwnProperty(value, key) {
     return isPropertyHost(value) &&
         Object.prototype.hasOwnProperty.call(value, key);
 }
 /**
- * @brief has own data property.
+ * @brief Test whether a value owns a stable data property.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Candidate property host.
+ * @param key Property key to inspect.
+ * @returns True when the key is present as a data descriptor.
  */
 function hasOwnDataProperty(value, key) {
     if (!isPropertyHost(value)) {
@@ -312,6 +526,8 @@ function hasOwnDataProperty(value, key) {
 }
 /**
  * @brief test strict keys.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function testStrictKeys(value, keys) {
     if (!isPlainRecord(value)) {
@@ -328,6 +544,8 @@ function testStrictKeys(value, keys) {
 }
 /**
  * @brief compare number.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function compareNumber(left, right, gte) {
     if (typeof left !== "number" || typeof right !== "number") {
@@ -337,6 +555,8 @@ function compareNumber(left, right, gte) {
 }
 /**
  * @brief test string bound.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function testStringBound(value, bound, min) {
     if (typeof value !== "string") {
@@ -346,6 +566,8 @@ function testStringBound(value, bound, min) {
 }
 /**
  * @brief test regex.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function testRegex(value, regex) {
     if (typeof value !== "string") {
@@ -357,25 +579,39 @@ function testRegex(value, regex) {
     return result;
 }
 /**
- * @brief is finite number.
+ * @brief Test the numeric domain accepted by TypeSea number schemas.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Candidate runtime value.
+ * @returns True for finite JavaScript numbers.
  */
 function isFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
 /**
- * @brief is plain record.
+ * @brief Test whether a value can satisfy object-like schema nodes.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Candidate runtime value.
+ * @returns True for non-null, non-array objects.
  */
 function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * @brief is property host.
+ * @brief Test whether descriptor APIs can inspect the value.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Candidate runtime value.
+ * @returns True for objects and functions.
  */
 function isPropertyHost(value) {
     return (typeof value === "object" && value !== null) || typeof value === "function";
 }
 /**
  * @brief acquire graph frame.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function acquireGraphFrame(state, nodeCount) {
     const index = state.graphDepth;
@@ -403,12 +639,15 @@ function acquireGraphFrame(state, nodeCount) {
 }
 /**
  * @brief release graph frame.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 function releaseGraphFrame(state) {
     state.graphDepth -= 1;
 }
 /**
- * @brief is strict true.
+ * @brief Check strict true.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function isStrictTrue(value) {
     return value === true;

package/dist/plan/schema-predicate.d.ts

@@ -1,15 +1,21 @@
 /**
  * @file schema-predicate.ts
  * @brief Schema-specialized predicate kernels for validation plans.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 import { type Schema } from "../schema/index.js";
 import type { ValidationState } from "../evaluate/state.js";
 /**
  * @brief child predicate runner.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 export type ChildPredicateRunner = (schema: Schema, value: unknown, state: ValidationState) => boolean;
 /**
  * @brief execute schema kernel.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 export declare function executeSchemaKernel(schema: Schema, value: unknown, state: ValidationState, runChild: ChildPredicateRunner): boolean;
 //# sourceMappingURL=schema-predicate.d.ts.map

package/dist/plan/schema-predicate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-predicate.d.ts","sourceRoot":"","sources":["../../src/plan/schema-predicate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAS5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,KACnB,OAAO,CAAC;AAEb;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAoDT"}
+{"version":3,"file":"schema-predicate.d.ts","sourceRoot":"","sources":["../../src/plan/schema-predicate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EAKH,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AAU5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAC/B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,KACrB,OAAO,CAAC;AAEb;;;;GAIG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,oBAAoB,GAC/B,OAAO,CAoDT"}