typesea 0.1.0 → 0.2.0

package/dist/ir/builder.js

@@ -1,29 +1,26 @@
 /**
  * @file builder.ts
  * @brief Dense graph builder with structural node interning.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
-import { NodeTag } from "../kind/index.js";
+import { NodeTag, PresenceTag } from "../kind/index.js";
 import { freezeGraph } from "./freeze.js";
 import { isPlainRegExp } from "./regexp.js";
 /**
- * @brief graph builder.
- * @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 Dense Sea-of-Nodes graph construction arena.
+ * @details The builder interns pure scalar nodes so later optimization passes see
+ * one canonical id for equivalent predicates. Composite nodes are deliberately
+ * appended instead: their embedded child graphs and schema payloads are owned
+ * values, and pointer-level interning would make aliasing harder to audit.
  */
 export class GraphBuilder {
     nodes;
     hash;
-    /**
-     * @brief constructor.
-       * @post The receiver is initialized according to the class invariant before it can be observed.
-     */
     constructor() {
         this.nodes = [];
         this.hash = new Map();
     }
-    /**
-     * @brief start.
-         */
     start() {
         return this.intern("start", (id) => ({
             id,
@@ -31,9 +28,6 @@ export class GraphBuilder {
             deps: []
         }));
     }
-    /**
-     * @brief param.
-           */
     param(name) {
         return this.intern(`param:${name}`, (id) => ({
             id,
@@ -42,10 +36,8 @@ export class GraphBuilder {
             name
         }));
     }
-    /**
-     * @brief constant.
-           */
     constant(value) {
+        /* Symbols are identity values; interning them by text would be unsound. */
         if (typeof value === "symbol") {
             return this.push((id) => ({
                 id,
@@ -62,9 +54,6 @@ export class GraphBuilder {
             value
         }));
     }
-    /**
-     * @brief get prop.
-             */
     getProp(object, key) {
         const hashKey = `getProp:${String(object)}:${key}`;
         return this.intern(hashKey, (id) => ({
@@ -75,75 +64,39 @@ export class GraphBuilder {
             key
         }));
     }
-    /**
-     * @brief is string.
-           */
     isString(value) {
         return this.unary(NodeTag.IsString, value);
     }
-    /**
-     * @brief is number.
-           */
     isNumber(value) {
         return this.unary(NodeTag.IsNumber, value);
     }
-    /**
-     * @brief is boolean.
-           */
     isBoolean(value) {
         return this.unary(NodeTag.IsBoolean, value);
     }
-    /**
-     * @brief is big int.
-           */
     isBigInt(value) {
         return this.unary(NodeTag.IsBigInt, value);
     }
-    /**
-     * @brief is symbol.
-           */
     isSymbol(value) {
         return this.unary(NodeTag.IsSymbol, value);
     }
-    /**
-     * @brief is object.
-           */
     isObject(value) {
         return this.unary(NodeTag.IsObject, value);
     }
-    /**
-     * @brief is array.
-           */
     isArray(value) {
         return this.unary(NodeTag.IsArray, value);
     }
-    /**
-     * @brief is undefined.
-           */
     isUndefined(value) {
         return this.unary(NodeTag.IsUndefined, value);
     }
-    /**
-     * @brief is null.
-           */
     isNull(value) {
         return this.unary(NodeTag.IsNull, value);
     }
-    /**
-     * @brief is integer.
-           */
     isInteger(value) {
         return this.unary(NodeTag.IsInteger, value);
     }
-    /**
-     * @brief not.
-           */
     not(value) {
         return this.unary(NodeTag.Not, value);
     }
-    /**
-     * @brief equals.
-             */
     equals(left, right) {
         const key = `eq:${String(left)}:${String(right)}`;
         return this.intern(key, (id) => ({
@@ -154,33 +107,18 @@ export class GraphBuilder {
             right
         }));
     }
-    /**
-     * @brief gte.
-             */
     gte(left, right) {
         return this.numeric(NodeTag.Gte, left, right);
     }
-    /**
-     * @brief lte.
-             */
     lte(left, right) {
         return this.numeric(NodeTag.Lte, left, right);
     }
-    /**
-     * @brief string min.
-             */
     stringMin(value, bound) {
         return this.stringBound(NodeTag.StringMin, value, bound);
     }
-    /**
-     * @brief string max.
-             */
     stringMax(value, bound) {
         return this.stringBound(NodeTag.StringMax, value, bound);
     }
-    /**
-     * @brief regex.
-               */
     regex(value, regex, name) {
         if (!isPlainRegExp(regex)) {
             throw new TypeError("regex node must use a plain RegExp");
@@ -198,9 +136,6 @@ export class GraphBuilder {
             name
         }));
     }
-    /**
-     * @brief has own.
-             */
     hasOwn(object, key) {
         const hashKey = `hasOwn:${String(object)}:${key}`;
         return this.intern(hashKey, (id) => ({
@@ -211,9 +146,6 @@ export class GraphBuilder {
             key
         }));
     }
-    /**
-     * @brief has own data.
-             */
     hasOwnData(object, key) {
         const hashKey = `hasOwnData:${String(object)}:${key}`;
         return this.intern(hashKey, (id) => ({
@@ -224,9 +156,6 @@ export class GraphBuilder {
             key
         }));
     }
-    /**
-     * @brief strict keys.
-             */
     strictKeys(object, keys) {
         const hashKey = `strictKeys:${String(object)}:${JSON.stringify(keys)}`;
         return this.intern(hashKey, (id) => ({
@@ -237,46 +166,37 @@ export class GraphBuilder {
             keys
         }));
     }
-    /**
-     * @brief array every.
-             */
-    arrayEvery(value, item) {
+    arrayEvery(value, item, itemGraph) {
         return this.push((id) => ({
             id,
             tag: NodeTag.ArrayEvery,
             deps: [value],
             value,
-            item
+            item,
+            itemGraph
         }));
     }
-    /**
-     * @brief tuple items.
-             */
-    tupleItems(value, items) {
+    tupleItems(value, items, itemGraphs) {
         return this.push((id) => ({
             id,
             tag: NodeTag.TupleItems,
             deps: [value],
             value,
-            items
+            items,
+            itemGraphs
         }));
     }
-    /**
-     * @brief record every.
-             */
-    recordEvery(value, item) {
+    recordEvery(value, item, itemGraph) {
         return this.push((id) => ({
             id,
             tag: NodeTag.RecordEvery,
             deps: [value],
             value,
-            item
+            item,
+            itemGraph
         }));
     }
-    /**
-     * @brief discriminant dispatch.
-             */
-    discriminantDispatch(value, key, literals, schemas) {
+    discriminantDispatch(value, key, literals, schemas, graphs) {
         return this.push((id) => ({
             id,
             tag: NodeTag.DiscriminantDispatch,
@@ -285,12 +205,43 @@ export class GraphBuilder {
             key,
             literals,
             schemas,
+            graphs,
             lookup: makeDiscriminantLookup(literals)
         }));
     }
-    /**
-     * @brief schema check.
-             */
+    objectShape(value, entries, keys, mode) {
+        return this.push((id) => ({
+            id,
+            tag: NodeTag.ObjectShape,
+            deps: [value],
+            value,
+            entries,
+            keys,
+            mode,
+            allRequired: objectShapeAllRequired(entries)
+        }));
+    }
+    unionDispatch(value, options, graphs, masks) {
+        return this.push((id) => ({
+            id,
+            tag: NodeTag.UnionDispatch,
+            deps: [value],
+            value,
+            options,
+            graphs,
+            masks
+        }));
+    }
+    primitiveUnion(value, graphs, masks) {
+        return this.push((id) => ({
+            id,
+            tag: NodeTag.PrimitiveUnion,
+            deps: [value],
+            value,
+            graphs,
+            masks
+        }));
+    }
     schemaCheck(value, schema) {
         return this.push((id) => ({
             id,
@@ -300,9 +251,6 @@ export class GraphBuilder {
             schema
         }));
     }
-    /**
-     * @brief and.
-           */
     and(values) {
         const first = values[0];
         if (first === undefined) {
@@ -319,9 +267,6 @@ export class GraphBuilder {
             values
         }));
     }
-    /**
-     * @brief or.
-           */
     or(values) {
         const first = values[0];
         if (first === undefined) {
@@ -338,9 +283,6 @@ export class GraphBuilder {
             values
         }));
     }
-    /**
-     * @brief ret.
-             */
     ret(control, value) {
         return this.push((id) => ({
             id,
@@ -350,9 +292,6 @@ export class GraphBuilder {
             value
         }));
     }
-    /**
-     * @brief finish.
-             */
     finish(entry, result) {
         return freezeGraph({
             nodes: this.nodes.slice(),
@@ -360,9 +299,6 @@ export class GraphBuilder {
             result
         });
     }
-    /**
-     * @brief unary.
-             */
     unary(tag, value) {
         const key = `unary:${String(tag)}:${String(value)}`;
         return this.intern(key, (id) => ({
@@ -372,9 +308,6 @@ export class GraphBuilder {
             value
         }));
     }
-    /**
-     * @brief numeric.
-               */
     numeric(tag, left, right) {
         const key = `numeric:${String(tag)}:${String(left)}:${String(right)}`;
         return this.intern(key, (id) => ({
@@ -385,9 +318,6 @@ export class GraphBuilder {
             right
         }));
     }
-    /**
-     * @brief string bound.
-               */
     stringBound(tag, value, bound) {
         const key = `stringBound:${String(tag)}:${String(value)}:${String(bound)}`;
         return this.intern(key, (id) => ({
@@ -398,9 +328,6 @@ export class GraphBuilder {
             bound
         }));
     }
-    /**
-     * @brief intern.
-             */
     intern(key, make) {
         const cached = this.hash.get(key);
         if (cached !== undefined) {
@@ -412,9 +339,6 @@ export class GraphBuilder {
         this.hash.set(key, id);
         return id;
     }
-    /**
-     * @brief push.
-           */
     push(make) {
         const id = this.nodes.length;
         const node = make(id);
@@ -423,23 +347,38 @@ export class GraphBuilder {
     }
 }
 /**
- * @brief make regex intern key.
- * @details Encodes each string segment with its byte-length-independent character length before concatenation.
- * @returns Collision-resistant intern key for one regex predicate identity.
+ * @brief Execute object shape all required.
+ * @details This helper keeps a local invariant explicit at the module boundary.
+ */
+function objectShapeAllRequired(entries) {
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (entry?.presence !== PresenceTag.Required) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * @brief Build an intern key without letting adjacent regex fields merge.
+ * @details Source, flags, and diagnostic name are all user-controlled strings;
+ * length prefixes keep `["ab", "c"]` distinct from `["a", "bc"]` without
+ * allocating wrapper tuples in the hot builder path.
  */
 function makeRegexInternKey(value, source, flags, name) {
     return `regex:${String(value)}:${lengthPrefixed(source)}${lengthPrefixed(flags)}${lengthPrefixed(name)}`;
 }
 /**
- * @brief length prefixed.
- * @details Preserves string tuple boundaries without allocating wrapper arrays or nested maps.
- * @returns Encoded string segment suitable for intern table keys.
+ * @brief Encode one string segment for a flat composite key.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 function lengthPrefixed(value) {
     return `${String(value.length)}:${value};`;
 }
 /**
- * @brief literal key.
+ * @brief Execute literal key.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function literalKey(value) {
     if (value === null) {
@@ -467,7 +406,8 @@ function literalKey(value) {
     return "undefined";
 }
 /**
- * @brief make discriminant lookup.
+ * @brief Build discriminant lookup.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function makeDiscriminantLookup(literals) {
     const lookup = Object.create(null);

package/dist/ir/freeze.d.ts

@@ -1,10 +1,14 @@
 /**
  * @file freeze.ts
  * @brief Immutable graph finalization.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 import type { Graph } from "./types.js";
 /**
  * @brief freeze graph.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 export declare function freezeGraph(graph: Graph): Graph;
 //# sourceMappingURL=freeze.d.ts.map

package/dist/ir/freeze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"freeze.d.ts","sourceRoot":"","sources":["../../src/ir/freeze.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAwB,MAAM,YAAY,CAAC;AAE9D;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAS/C"}
+{"version":3,"file":"freeze.d.ts","sourceRoot":"","sources":["../../src/ir/freeze.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAwB,MAAM,YAAY,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAS/C"}

package/dist/ir/freeze.js

@@ -1,12 +1,16 @@
 /**
  * @file freeze.ts
  * @brief Immutable graph finalization.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 import { NodeTag } from "../kind/index.js";
 import { freezeSchema } from "../schema/index.js";
 import { isPlainRegExp } from "./regexp.js";
 /**
  * @brief freeze graph.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 export function freezeGraph(graph) {
     for (let index = 0; index < graph.nodes.length; index += 1) {
@@ -20,6 +24,8 @@ export function freezeGraph(graph) {
 }
 /**
  * @brief freeze graph node.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 function freezeGraphNode(node) {
     Object.freeze(node.deps);
@@ -32,6 +38,7 @@ function freezeGraphNode(node) {
             break;
         case NodeTag.ArrayEvery:
             freezeSchema(node.item);
+            freezeGraph(node.itemGraph);
             break;
         case NodeTag.TupleItems:
             for (let index = 0; index < node.items.length; index += 1) {
@@ -39,11 +46,17 @@ function freezeGraphNode(node) {
                 if (item !== undefined) {
                     freezeSchema(item);
                 }
+                const graph = node.itemGraphs[index];
+                if (graph !== undefined) {
+                    freezeGraph(graph);
+                }
             }
             Object.freeze(node.items);
+            Object.freeze(node.itemGraphs);
             break;
         case NodeTag.RecordEvery:
             freezeSchema(node.item);
+            freezeGraph(node.itemGraph);
             break;
         case NodeTag.DiscriminantDispatch:
             Object.freeze(node.literals);
@@ -52,10 +65,52 @@ function freezeGraphNode(node) {
                 if (schema !== undefined) {
                     freezeSchema(schema);
                 }
+                const graph = node.graphs[index];
+                if (graph !== undefined) {
+                    freezeGraph(graph);
+                }
             }
             Object.freeze(node.schemas);
+            Object.freeze(node.graphs);
             Object.freeze(node.lookup);
             break;
+        case NodeTag.ObjectShape:
+            for (let index = 0; index < node.entries.length; index += 1) {
+                const entry = node.entries[index];
+                if (entry !== undefined) {
+                    freezeSchema(entry.schema);
+                    freezeGraph(entry.graph);
+                    Object.freeze(entry);
+                }
+            }
+            Object.freeze(node.entries);
+            Object.freeze(node.keys);
+            break;
+        case NodeTag.UnionDispatch:
+            for (let index = 0; index < node.options.length; index += 1) {
+                const schema = node.options[index];
+                if (schema !== undefined) {
+                    freezeSchema(schema);
+                }
+                const graph = node.graphs[index];
+                if (graph !== undefined) {
+                    freezeGraph(graph);
+                }
+            }
+            Object.freeze(node.options);
+            Object.freeze(node.graphs);
+            Object.freeze(node.masks);
+            break;
+        case NodeTag.PrimitiveUnion:
+            for (let index = 0; index < node.graphs.length; index += 1) {
+                const graph = node.graphs[index];
+                if (graph !== undefined) {
+                    freezeGraph(graph);
+                }
+            }
+            Object.freeze(node.graphs);
+            Object.freeze(node.masks);
+            break;
         case NodeTag.SchemaCheck:
             freezeSchema(node.schema);
             break;
@@ -70,6 +125,8 @@ function freezeGraphNode(node) {
 }
 /**
  * @brief freeze regex node.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 function freezeRegexNode(node) {
     const regex = node.regex;
@@ -94,6 +151,8 @@ function freezeRegexNode(node) {
 }
 /**
  * @brief clone graph reg exp.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 function cloneGraphRegExp(regex) {
     const cloned = new RegExp(regex.source, regex.flags);

package/dist/ir/index.d.ts

@@ -1,9 +1,11 @@
 /**
  * @file index.ts
  * @brief Public IR module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { GraphBuilder } from "./builder.js";
 export { freezeGraph } from "./freeze.js";
 export { isGraphValue } from "./validate.js";
-export type { ArrayEveryNode, BooleanFoldNode, ConstNode, DiscriminantDispatchLookup, DiscriminantDispatchNode, EqualsNode, GetPropNode, Graph, GraphNode, HasOwnDataNode, HasOwnNode, NodeId, NumericCompareNode, ParamNode, RecordEveryNode, RegexNode, ReturnNode, SchemaCheckNode, StartNode, StrictKeysNode, StringBoundNode, TupleItemsNode, UnaryPredicateNode } from "./types.js";
+export type { ArrayEveryNode, BooleanFoldNode, ConstNode, DiscriminantDispatchLookup, DiscriminantDispatchNode, EqualsNode, GetPropNode, Graph, GraphNode, HasOwnDataNode, HasOwnNode, NodeId, ObjectShapeEntry, ObjectShapeNode, NumericCompareNode, ParamNode, PrimitiveUnionNode, RecordEveryNode, RegexNode, ReturnNode, SchemaCheckNode, StartNode, StrictKeysNode, StringBoundNode, TupleItemsNode, UnionDispatchMask, UnionDispatchNode, UnaryPredicateNode } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ir/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EACV,cAAc,EACd,eAAe,EACf,SAAS,EACT,0BAA0B,EAC1B,wBAAwB,EACxB,UAAU,EACV,WAAW,EACX,KAAK,EACL,SAAS,EACT,cAAc,EACd,UAAU,EACV,MAAM,EACN,kBAAkB,EAClB,SAAS,EACT,eAAe,EACf,SAAS,EACT,UAAU,EACV,eAAe,EACf,SAAS,EACT,cAAc,EACd,eAAe,EACf,cAAc,EACd,kBAAkB,EACnB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ir/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EACR,cAAc,EACd,eAAe,EACf,SAAS,EACT,0BAA0B,EAC1B,wBAAwB,EACxB,UAAU,EACV,WAAW,EACX,KAAK,EACL,SAAS,EACT,cAAc,EACd,UAAU,EACV,MAAM,EACN,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,UAAU,EACV,eAAe,EACf,SAAS,EACT,cAAc,EACd,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EACrB,MAAM,YAAY,CAAC"}

package/dist/ir/index.js

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public IR module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { GraphBuilder } from "./builder.js";
 export { freezeGraph } from "./freeze.js";

package/dist/ir/regexp.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file regexp.ts
  * @brief RegExp shape guard for graph nodes.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 export declare function isPlainRegExp(value: unknown): value is RegExp;
 //# sourceMappingURL=regexp.d.ts.map

package/dist/ir/regexp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regexp.d.ts","sourceRoot":"","sources":["../../src/ir/regexp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAO7D"}
+{"version":3,"file":"regexp.d.ts","sourceRoot":"","sources":["../../src/ir/regexp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAO7D"}

package/dist/ir/regexp.js

@@ -1,6 +1,8 @@
 /**
  * @file regexp.ts
  * @brief RegExp shape guard for graph nodes.
+ * @details IR helpers preserve Sea-of-Nodes invariants before graphs cross optimizer,
+ * compiler, or public introspection boundaries.
  */
 export function isPlainRegExp(value) {
     return value instanceof RegExp &&