typesea 0.1.0 → 0.3.0

package/dist/optimize/fold-boolean.js

@@ -1,15 +1,27 @@
 /**
  * @file fold-boolean.ts
  * @brief Constant folding for boolean fold nodes.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import { ensureConst, keep, readConst, replace } from "./fold-common.js";
+import { flattenBooleanValues, simplifyAndValues, simplifyOrValues } from "./algebraic.js";
+import { canonicalizeAndValues, canonicalizeOrValues } from "./fold-constraints.js";
 /**
- * @brief fold and.
+ * @brief Simplify an `And` fold node using boolean identities and constraints.
+ * @details False annihilates the whole conjunction, true disappears, nested
+ * conjunctions are flattened, and scalar constraints are canonicalized after
+ * algebraic simplification.
+ * @param node Boolean fold node to simplify.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the conjunction.
  */
 export function foldAnd(node, nodes, aliases) {
     const values = [];
-    for (let index = 0; index < node.values.length; index += 1) {
-        const value = node.values[index];
+    const flattened = flattenBooleanValues(node.values, nodes, node.tag);
+    for (let index = 0; index < flattened.length; index += 1) {
+        const value = flattened[index];
         if (value === undefined) {
             continue;
         }
@@ -25,8 +37,23 @@ export function foldAnd(node, nodes, aliases) {
     if (values.length === 0) {
         return replace(node, ensureConst(nodes, aliases, true));
     }
-    if (values.length === 1) {
-        const only = values[0];
+    const algebraic = simplifyAndValues(values, nodes);
+    if (algebraic.contradiction) {
+        return replace(node, ensureConst(nodes, aliases, false));
+    }
+    if (algebraic.values.length === 0) {
+        return replace(node, ensureConst(nodes, aliases, true));
+    }
+    const canonical = canonicalizeAndValues(algebraic.values, nodes);
+    if (canonical.contradiction) {
+        return replace(node, ensureConst(nodes, aliases, false));
+    }
+    const canonicalValues = canonical.values;
+    if (canonicalValues.length === 0) {
+        return replace(node, ensureConst(nodes, aliases, true));
+    }
+    if (canonicalValues.length === 1) {
+        const only = canonicalValues[0];
         if (only !== undefined) {
             return replace(node, only);
         }
@@ -34,17 +61,24 @@ export function foldAnd(node, nodes, aliases) {
     return keep({
         id: node.id,
         tag: node.tag,
-        deps: values,
-        values
+        deps: canonicalValues,
+        values: canonicalValues
     });
 }
 /**
- * @brief fold or.
+ * @brief Simplify an `Or` fold node using boolean identities and tautologies.
+ * @details True satisfies the whole disjunction, false disappears, nested
+ * disjunctions are flattened, and duplicate surviving arms are removed.
+ * @param node Boolean fold node to simplify.
+ * @param nodes Mutable graph node table for constant interning.
+ * @param aliases Mutable alias table updated when a constant is inserted.
+ * @returns Fold result for the disjunction.
  */
 export function foldOr(node, nodes, aliases) {
     const values = [];
-    for (let index = 0; index < node.values.length; index += 1) {
-        const value = node.values[index];
+    const flattened = flattenBooleanValues(node.values, nodes, node.tag);
+    for (let index = 0; index < flattened.length; index += 1) {
+        const value = flattened[index];
         if (value === undefined) {
             continue;
         }
@@ -60,8 +94,19 @@ export function foldOr(node, nodes, aliases) {
     if (values.length === 0) {
         return replace(node, ensureConst(nodes, aliases, false));
     }
-    if (values.length === 1) {
-        const only = values[0];
+    const algebraic = simplifyOrValues(values, nodes);
+    if (algebraic.tautology) {
+        return replace(node, ensureConst(nodes, aliases, true));
+    }
+    if (algebraic.values.length === 0) {
+        return replace(node, ensureConst(nodes, aliases, false));
+    }
+    const canonicalValues = canonicalizeOrValues(algebraic.values);
+    if (canonicalValues.length === 0) {
+        return replace(node, ensureConst(nodes, aliases, false));
+    }
+    if (canonicalValues.length === 1) {
+        const only = canonicalValues[0];
         if (only !== undefined) {
             return replace(node, only);
         }
@@ -69,7 +114,7 @@ export function foldOr(node, nodes, aliases) {
     return keep({
         id: node.id,
         tag: node.tag,
-        deps: values,
-        values
+        deps: canonicalValues,
+        values: canonicalValues
     });
 }

package/dist/optimize/fold-common.d.ts

@@ -1,45 +1,80 @@
 /**
  * @file fold-common.ts
  * @brief Shared constant-folding helpers.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import type { GraphNode, NodeId } from "../ir/index.js";
 import type { LiteralValue } from "../schema/index.js";
 /**
- * @brief const read.
+ * @brief Result of probing a node slot for a constant value.
+ * @details `found` is separate from `value` because `undefined` is itself a
+ * valid literal constant in the graph.
  */
 export interface ConstRead {
     readonly found: boolean;
     readonly value: LiteralValue | undefined;
 }
 /**
- * @brief fold result.
+ * @brief Node rewrite result returned by scalar folding helpers.
+ * @details The node carries the possibly edited payload while `replacement`
+ * records aliasing information for later dependency rewrites.
  */
 export interface FoldResult {
     readonly node: GraphNode;
     readonly replacement: NodeId | undefined;
 }
 /**
- * @brief ensure const.
+ * @brief Reuse or append a constant node for a literal value.
+ * @details Constants are interned with `Object.is` so NaN, -0, and undefined
+ * keep JavaScript literal identity semantics. The alias table is updated
+ * immediately because later folders may depend on the new node id.
+ * @param nodes Mutable graph node table for the folding pass.
+ * @param aliases Mutable node alias table kept in step with `nodes`.
+ * @param value Literal value that must exist in the graph.
+ * @returns Node id of the existing or newly appended constant.
  */
 export declare function ensureConst(nodes: GraphNode[], aliases: NodeId[], value: LiteralValue): NodeId;
 /**
- * @brief read const.
+ * @brief Probe a node id for an IR constant without conflating misses.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param nodes Graph node table being optimized.
+ * @param id Node id to inspect.
+ * @returns Const probe result with an explicit found bit.
  */
 export declare function readConst(nodes: readonly GraphNode[], id: NodeId): ConstRead;
 /**
- * @brief keep.
+ * @brief Return a fold result that keeps the node in place.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param node Node after local payload edits.
+ * @returns Fold result without an alias replacement.
  */
 export declare function keep(node: GraphNode): FoldResult;
 /**
- * @brief replace.
+ * @brief Return a fold result that aliases this node to another node id.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param node Original node retained for pass bookkeeping.
+ * @param replacement Node id that should replace references to `node`.
+ * @returns Fold result carrying the alias replacement.
  */
 export declare function replace(node: GraphNode, replacement: NodeId): FoldResult;
 /**
- * @brief is finite number.
+ * @brief Check whether a value is a finite JavaScript number.
+ * @details Numeric bound folding excludes NaN and infinities because order
+ * comparisons against those values do not form useful closed validation ranges.
+ * @param value Candidate literal value.
+ * @returns True when the value is a finite number.
  */
 export declare function isFiniteNumber(value: unknown): boolean;
 /**
- * @brief is plain record.
+ * @brief Check whether a value is an object-like record for fold metadata.
+ * @details Arrays are excluded because optimizer metadata objects use named
+ * fields, and accepting arrays would hide malformed pass state.
+ * @param value Candidate metadata value.
+ * @returns True when the value is a non-array object.
  */
 export declare function isPlainRecord(value: unknown): boolean;
 //# sourceMappingURL=fold-common.d.ts.map

package/dist/optimize/fold-common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fold-common.d.ts","sourceRoot":"","sources":["../../src/optimize/fold-common.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,YAAY,GAClB,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CAY5E;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,CAKhD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAKxE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAErD"}
+{"version":3,"file":"fold-common.d.ts","sourceRoot":"","sources":["../../src/optimize/fold-common.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACvB,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,YAAY,GACpB,MAAM,CAgBR;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CAY5E;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,CAKhD;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAKxE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAErD"}

package/dist/optimize/fold-common.js

@@ -1,10 +1,19 @@
 /**
  * @file fold-common.ts
  * @brief Shared constant-folding helpers.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import { NodeTag } from "../kind/index.js";
 /**
- * @brief ensure const.
+ * @brief Reuse or append a constant node for a literal value.
+ * @details Constants are interned with `Object.is` so NaN, -0, and undefined
+ * keep JavaScript literal identity semantics. The alias table is updated
+ * immediately because later folders may depend on the new node id.
+ * @param nodes Mutable graph node table for the folding pass.
+ * @param aliases Mutable node alias table kept in step with `nodes`.
+ * @param value Literal value that must exist in the graph.
+ * @returns Node id of the existing or newly appended constant.
  */
 export function ensureConst(nodes, aliases, value) {
     for (let index = 0; index < nodes.length; index += 1) {
@@ -24,7 +33,12 @@ export function ensureConst(nodes, aliases, value) {
     return id;
 }
 /**
- * @brief read const.
+ * @brief Probe a node id for an IR constant without conflating misses.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param nodes Graph node table being optimized.
+ * @param id Node id to inspect.
+ * @returns Const probe result with an explicit found bit.
  */
 export function readConst(nodes, id) {
     const node = nodes[id];
@@ -40,7 +54,11 @@ export function readConst(nodes, id) {
     };
 }
 /**
- * @brief keep.
+ * @brief Return a fold result that keeps the node in place.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param node Node after local payload edits.
+ * @returns Fold result without an alias replacement.
  */
 export function keep(node) {
     return {
@@ -49,7 +67,12 @@ export function keep(node) {
     };
 }
 /**
- * @brief replace.
+ * @brief Return a fold result that aliases this node to another node id.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param node Original node retained for pass bookkeeping.
+ * @param replacement Node id that should replace references to `node`.
+ * @returns Fold result carrying the alias replacement.
  */
 export function replace(node, replacement) {
     return {
@@ -58,13 +81,21 @@ export function replace(node, replacement) {
     };
 }
 /**
- * @brief is finite number.
+ * @brief Check whether a value is a finite JavaScript number.
+ * @details Numeric bound folding excludes NaN and infinities because order
+ * comparisons against those values do not form useful closed validation ranges.
+ * @param value Candidate literal value.
+ * @returns True when the value is a finite number.
  */
 export function isFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
 /**
- * @brief is plain record.
+ * @brief Check whether a value is an object-like record for fold metadata.
+ * @details Arrays are excluded because optimizer metadata objects use named
+ * fields, and accepting arrays would hide malformed pass state.
+ * @param value Candidate metadata value.
+ * @returns True when the value is a non-array object.
  */
 export function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/optimize/fold-constraints.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file fold-constraints.ts
+ * @brief Boolean constraint canonicalization for pure predicate runs.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ */
+import type { GraphNode, NodeId } from "../ir/index.js";
+/**
+ * @brief Canonicalized input list for a boolean fold node.
+ * @details Contradictions are represented separately from an empty value list so
+ * callers can distinguish a provably false conjunction from a fold that simply
+ * had no surviving children.
+ */
+export interface ConstraintFold {
+    readonly contradiction: boolean;
+    readonly values: readonly NodeId[];
+}
+/**
+ * @brief canonicalize and values.
+ * @details Removes duplicate predicates and dominated scalar bounds while keeping
+ * the first observable execution order intact. Only the pure prefix may collapse
+ * the whole conjunction to `false`.
+ * @returns Canonical node id vector or a contradiction marker.
+ */
+export declare function canonicalizeAndValues(values: readonly NodeId[], nodes: readonly GraphNode[]): ConstraintFold;
+/**
+ * @brief canonicalize or values.
+ * @details Removes repeated node ids. Repeated ids are already memoized by graph
+ * execution, so this only shrinks emitted boolean expressions.
+ * @returns Canonical node id vector.
+ */
+export declare function canonicalizeOrValues(values: readonly NodeId[]): readonly NodeId[];
+//# sourceMappingURL=fold-constraints.d.ts.map

package/dist/optimize/fold-constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-constraints.d.ts","sourceRoot":"","sources":["../../src/optimize/fold-constraints.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACR,SAAS,EACT,MAAM,EACT,MAAM,gBAAgB,CAAC;AAGxB;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAoED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACjC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,KAAK,EAAE,SAAS,SAAS,EAAE,GAC5B,cAAc,CA6BhB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAYjF"}