typesea 0.1.0 → 0.2.0

package/dist/message/index.js

@@ -1,13 +1,22 @@
 import { copyIssueArray, freezeIssueArray, isIssueCodeValue, makeIssue } from "../issue/index.js";
 import { err } from "../result/index.js";
 /**
- * @brief define messages.
+ * @brief Freeze a user catalog after validating its keys and templates.
+ * @details Message helpers keep structured issues separate from human-readable formatting
+ * until callers request text.
+ * @param catalog Partial message catalog supplied by the application.
+ * @returns Frozen catalog that can be reused across validations.
  */
 export function defineMessages(catalog) {
     return Object.freeze(copyCatalog(catalog));
 }
 /**
- * @brief format issue.
+ * @brief Render one issue into a localized human-readable message.
+ * @details The issue is copied before rendering so user callbacks cannot mutate
+ * shared diagnostic objects through accidental aliasing.
+ * @param issue Issue object to render.
+ * @param options Optional locale, catalog, and path formatter.
+ * @returns Rendered message text.
  */
 export function formatIssue(issue, options) {
     const copied = copyIssueArray([issue]);
@@ -18,7 +27,12 @@ export function formatIssue(issue, options) {
     return renderIssue(first, readOptions(options));
 }
 /**
- * @brief format issues.
+ * @brief Render a frozen list of issues into localized message strings.
+ * @details The issue array is copied before rendering so caller-owned issue
+ * objects cannot change while user path formatters or templates execute.
+ * @param issues Issue list to render.
+ * @param options Optional locale, catalog, and path formatter.
+ * @returns Frozen list of rendered messages aligned with the input issue order.
  */
 export function formatIssues(issues, options) {
     const copied = copyIssueArray(issues);
@@ -33,7 +47,13 @@ export function formatIssues(issues, options) {
     return Object.freeze(messages);
 }
 /**
- * @brief with messages.
+ * @brief Attach rendered messages to every issue in a failed check result.
+ * @details Successful results are returned unchanged. Failed results are copied
+ * into fresh issue objects so structured diagnostics keep their original fields
+ * while gaining a stable human-readable message.
+ * @param result Check result to decorate.
+ * @param options Optional locale, catalog, and path formatter.
+ * @returns Original success result or a failed result with rendered messages.
  */
 export function withMessages(result, options) {
     if (result.ok) {
@@ -51,7 +71,13 @@ export function withMessages(result, options) {
     return err(freezeIssueArray(issues));
 }
 /**
- * @brief render issue.
+ * @brief Select the template source and render one normalized issue.
+ * @details Custom catalogs take precedence, issue-local messages are respected
+ * next, and built-in catalogs are the final fallback. That order lets adapters
+ * inject precise messages without losing defaults.
+ * @param issue Issue currently being rendered.
+ * @param options Resolved message rendering configuration.
+ * @returns Rendered message text.
  */
 function renderIssue(issue, options) {
     const context = makeContext(issue, options.pathFormatter);
@@ -65,7 +91,12 @@ function renderIssue(issue, options) {
     return renderTemplate(defaultCatalogs[options.locale][issue.code], issue, context);
 }
 /**
- * @brief make context.
+ * @brief Build the stable template context for one issue.
+ * @details Missing expected or actual fields become `"unknown"` so templates
+ * can stay branch-free and every placeholder always has a string value.
+ * @param issue Issue currently being rendered.
+ * @param pathFormatter Formatter selected by resolved options.
+ * @returns Context object passed to string and function templates.
  */
 function makeContext(issue, pathFormatter) {
     return {
@@ -76,7 +107,14 @@ function makeContext(issue, pathFormatter) {
     };
 }
 /**
- * @brief render template.
+ * @brief Render a string or callback template against one issue context.
+ * @details Function templates are checked at runtime because they cross into
+ * user code. String templates use fixed token replacement without regular
+ * expressions, keeping the common path allocation pattern predictable.
+ * @param template Template selected for this issue code.
+ * @param issue Issue currently being rendered.
+ * @param context Preformatted replacement context.
+ * @returns Rendered message text.
  */
 function renderTemplate(template, issue, context) {
     if (typeof template === "function") {
@@ -93,7 +131,11 @@ function renderTemplate(template, issue, context) {
         .split("{actual}").join(context.actual);
 }
 /**
- * @brief read options.
+ * @brief Normalize public rendering options into the internal shape.
+ * @details Validation happens once at the entry point. The render loop then
+ * works with concrete locale and formatter values without repeated guards.
+ * @param options Optional user configuration.
+ * @returns Resolved message rendering configuration.
  */
 function readOptions(options) {
     if (options === undefined) {
@@ -116,7 +158,11 @@ function readOptions(options) {
     };
 }
 /**
- * @brief read locale.
+ * @brief Validate and normalize the requested message locale.
+ * @details Message helpers keep structured issues separate from human-readable formatting
+ * until callers request text.
+ * @param value Locale field from the public options object.
+ * @returns Built-in locale identifier, defaulting to English.
  */
 function readLocale(value) {
     if (value === undefined || value === "en") {
@@ -128,7 +174,12 @@ function readLocale(value) {
     throw new TypeError("message locale must be en or ko");
 }
 /**
- * @brief read path formatter.
+ * @brief Validate the optional user path formatter.
+ * @details The returned wrapper enforces the string return contract at the
+ * boundary where user code is invoked, keeping downstream template replacement
+ * code simple.
+ * @param value Formatter value from public options.
+ * @returns Safe formatter callback used by the renderer.
  */
 function readPathFormatter(value) {
     if (value === undefined) {
@@ -147,7 +198,12 @@ function readPathFormatter(value) {
     };
 }
 /**
- * @brief copy catalog.
+ * @brief Validate and copy a user message catalog.
+ * @details The renderer stores only recognized issue-code keys and accepted
+ * template forms. Copying also prevents later caller mutation from changing
+ * messages during validation.
+ * @param value Candidate catalog object.
+ * @returns Catalog copy accepted by the renderer.
  */
 function copyCatalog(value) {
     if (!isRecord(value)) {
@@ -172,13 +228,21 @@ function copyCatalog(value) {
     return copied;
 }
 /**
- * @brief is issue message template.
+ * @brief Check whether a catalog value is an accepted template form.
+ * @details Message helpers keep structured issues separate from human-readable formatting
+ * until callers request text.
+ * @param value Candidate catalog entry value.
+ * @returns True for string templates or formatter functions.
  */
 function isIssueMessageTemplate(value) {
     return typeof value === "string" || typeof value === "function";
 }
 /**
- * @brief default path formatter.
+ * @brief Render a TypeSea issue path using JSON-like bracket segments.
+ * @details The root is `$`, numeric segments render as indexes, and string
+ * segments are JSON-escaped so dots or brackets in field names stay unambiguous.
+ * @param path Issue path to render.
+ * @returns Stable path string for message templates.
  */
 function defaultPathFormatter(path) {
     if (path.length === 0) {
@@ -197,13 +261,16 @@ function defaultPathFormatter(path) {
     return result;
 }
 /**
- * @brief is record.
+ * @brief Check record.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * @brief en catalog.
+ * @brief Built-in English issue message catalog.
+ * @details Templates stay terse and token-based so the same renderer can handle
+ * built-in and user-defined catalogs without locale-specific code paths.
  */
 const enCatalog = Object.freeze({
     expected_string: "Expected string at {path}; received {actual}.",
@@ -232,7 +299,9 @@ const enCatalog = Object.freeze({
     unrecognized_key: "Unrecognized key at {path}; expected {expected}."
 });
 /**
- * @brief ko catalog.
+ * @brief Built-in Korean issue message catalog.
+ * @details The catalog mirrors English issue-code coverage exactly so locale
+ * switching cannot expose missing template keys at runtime.
  */
 const koCatalog = Object.freeze({
     expected_string: "{path}에서 문자열이 필요하지만 {actual}을 받았습니다.",
@@ -261,7 +330,9 @@ const koCatalog = Object.freeze({
     unrecognized_key: "{path}에서 알 수 없는 키입니다. 기대값은 {expected}입니다."
 });
 /**
- * @brief default catalogs.
+ * @brief Frozen lookup table for built-in message catalogs.
+ * @details The table is keyed by normalized locale values, letting renderIssue
+ * index without optional fallback logic after option resolution.
  */
 const defaultCatalogs = Object.freeze({
     en: enCatalog,

package/dist/optimize/algebraic.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file algebraic.ts
+ * @brief Boolean algebra simplification for validation predicates.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ */
+import { NodeTag } from "../kind/index.js";
+import type { GraphNode, NodeId } from "../ir/index.js";
+export interface AlgebraicFold {
+    /**
+     * @brief True when an And fold has proven false.
+     * @details The caller replaces the whole conjunction with a constant false node.
+     */
+    readonly contradiction: boolean;
+    /**
+     * @brief True when an Or fold has proven true.
+     * @details The caller replaces the whole disjunction with a constant true node.
+     */
+    readonly tautology: boolean;
+    /**
+     * @brief Remaining operand ids after algebraic simplification.
+     * @details Operand order is preserved so generated code keeps stable branch ordering.
+     */
+    readonly values: readonly NodeId[];
+}
+/**
+ * @brief Flatten nested boolean folds of the same kind.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Input operand ids.
+ * @param nodes Graph node table used to inspect nested folds.
+ * @param tag Boolean fold kind to flatten.
+ * @returns Operand list with same-kind nested folds expanded in place.
+ */
+export declare function flattenBooleanValues(values: readonly NodeId[], nodes: readonly GraphNode[], tag: typeof NodeTag.And | typeof NodeTag.Or): readonly NodeId[];
+/**
+ * @brief Simplify operands of an And fold.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Input operand ids.
+ * @param nodes Graph node table used to inspect nested complement forms.
+ * @returns Simplification result with contradiction status and kept operands.
+ */
+export declare function simplifyAndValues(values: readonly NodeId[], nodes: readonly GraphNode[]): AlgebraicFold;
+/**
+ * @brief Simplify operands of an Or fold.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Input operand ids.
+ * @param nodes Graph node table used to inspect nested complement forms.
+ * @returns Simplification result with tautology status and kept operands.
+ */
+export declare function simplifyOrValues(values: readonly NodeId[], nodes: readonly GraphNode[]): AlgebraicFold;
+//# sourceMappingURL=algebraic.d.ts.map

package/dist/optimize/algebraic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"algebraic.d.ts","sourceRoot":"","sources":["../../src/optimize/algebraic.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,KAAK,EACR,SAAS,EACT,MAAM,EACT,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,aAAa;IAC1B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAChC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,GAAG,EAAE,OAAO,OAAO,CAAC,GAAG,GAAG,OAAO,OAAO,CAAC,EAAE,GAC5C,SAAS,MAAM,EAAE,CAmBnB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,KAAK,EAAE,SAAS,SAAS,EAAE,GAC5B,aAAa,CAuCf;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,KAAK,EAAE,SAAS,SAAS,EAAE,GAC5B,aAAa,CAuCf"}

package/dist/optimize/algebraic.js

@@ -0,0 +1,314 @@
+/**
+ * @file algebraic.ts
+ * @brief Boolean algebra simplification for validation predicates.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ */
+import { NodeTag } from "../kind/index.js";
+/**
+ * @brief Flatten nested boolean folds of the same kind.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Input operand ids.
+ * @param nodes Graph node table used to inspect nested folds.
+ * @param tag Boolean fold kind to flatten.
+ * @returns Operand list with same-kind nested folds expanded in place.
+ */
+export function flattenBooleanValues(values, nodes, tag) {
+    const flattened = [];
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined) {
+            continue;
+        }
+        const node = nodes[value];
+        if (node?.tag === tag) {
+            /*
+             * And(And(a,b),c) and Or(Or(a,b),c) are associative. Flattening
+             * reduces later duplicate and complement checks to one linear pass.
+             */
+            appendFlattenedBooleanValues(flattened, node.values, nodes, tag);
+        }
+        else {
+            flattened.push(value);
+        }
+    }
+    return flattened;
+}
+/**
+ * @brief Simplify operands of an And fold.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Input operand ids.
+ * @param nodes Graph node table used to inspect nested complement forms.
+ * @returns Simplification result with contradiction status and kept operands.
+ */
+export function simplifyAndValues(values, nodes) {
+    const kept = [];
+    const seen = new Set();
+    const positive = new Set();
+    const negative = new Set();
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined || seen.has(value)) {
+            continue;
+        }
+        if (isAbsorbedAndValue(value, nodes, seen)) {
+            /*
+             * a && (a || b) is equivalent to a. The Or branch cannot make the
+             * validation stricter once the shared value is already required.
+             */
+            continue;
+        }
+        if (hasComplementConflict(value, nodes, positive, negative)) {
+            /*
+             * a && !a is impossible for side-effect-free predicate nodes. Only
+             * complement-safe nodes are allowed into the positive/negative sets.
+             */
+            return {
+                contradiction: true,
+                tautology: false,
+                values: []
+            };
+        }
+        rememberComplementValue(value, nodes, positive, negative);
+        seen.add(value);
+        kept.push(value);
+    }
+    return {
+        contradiction: false,
+        tautology: false,
+        values: kept
+    };
+}
+/**
+ * @brief Simplify operands of an Or fold.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Input operand ids.
+ * @param nodes Graph node table used to inspect nested complement forms.
+ * @returns Simplification result with tautology status and kept operands.
+ */
+export function simplifyOrValues(values, nodes) {
+    const kept = [];
+    const seen = new Set();
+    const positive = new Set();
+    const negative = new Set();
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined || seen.has(value)) {
+            continue;
+        }
+        if (isAbsorbedOrValue(value, nodes, seen)) {
+            /*
+             * a || (a && b) is equivalent to a. The And branch cannot widen the
+             * accepted set once the shared value already passes.
+             */
+            continue;
+        }
+        if (hasComplementConflict(value, nodes, positive, negative)) {
+            /*
+             * a || !a is always true for complement-safe predicates, so the Or
+             * fold can collapse to a tautology.
+             */
+            return {
+                contradiction: false,
+                tautology: true,
+                values: []
+            };
+        }
+        rememberComplementValue(value, nodes, positive, negative);
+        seen.add(value);
+        kept.push(value);
+    }
+    return {
+        contradiction: false,
+        tautology: false,
+        values: kept
+    };
+}
+/**
+ * @brief Recursively append flattened operands.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param output Destination operand list.
+ * @param values Source operand ids.
+ * @param nodes Graph node table used to inspect nested folds.
+ * @param tag Boolean fold kind to flatten.
+ */
+function appendFlattenedBooleanValues(output, values, nodes, tag) {
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined) {
+            continue;
+        }
+        const node = nodes[value];
+        if (node?.tag === tag) {
+            appendFlattenedBooleanValues(output, node.values, nodes, tag);
+        }
+        else {
+            output.push(value);
+        }
+    }
+}
+/**
+ * @brief Test And absorption for `a && (a || b)`.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate operand id.
+ * @param nodes Graph node table.
+ * @param seen Operands already kept by the parent And.
+ * @returns True when the candidate is redundant.
+ */
+function isAbsorbedAndValue(value, nodes, seen) {
+    const node = nodes[value];
+    if (node?.tag !== NodeTag.Or) {
+        return false;
+    }
+    return containsSeenValue(node.values, seen);
+}
+/**
+ * @brief Test Or absorption for `a || (a && b)`.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate operand id.
+ * @param nodes Graph node table.
+ * @param seen Operands already kept by the parent Or.
+ * @returns True when the candidate is redundant.
+ */
+function isAbsorbedOrValue(value, nodes, seen) {
+    const node = nodes[value];
+    if (node?.tag !== NodeTag.And) {
+        return false;
+    }
+    return containsSeenValue(node.values, seen);
+}
+/**
+ * @brief Test whether a nested fold contains an operand already kept.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Nested fold operand ids.
+ * @param seen Parent fold operands already kept.
+ * @returns True when the nested fold repeats a kept operand.
+ */
+function containsSeenValue(values, seen) {
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value !== undefined && seen.has(value)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * @brief Detect a positive/negative complement conflict.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate operand id.
+ * @param nodes Graph node table.
+ * @param positive Complement-safe positive operands already seen.
+ * @param negative Complement-safe negated operands already seen.
+ * @returns True when the candidate conflicts with prior operands.
+ */
+function hasComplementConflict(value, nodes, positive, negative) {
+    const negated = readNegatedValue(value, nodes);
+    if (negated !== undefined) {
+        return isComplementSafe(negated, nodes) && positive.has(negated);
+    }
+    return isComplementSafe(value, nodes) && negative.has(value);
+}
+/**
+ * @brief Record a complement-safe operand in positive or negative form.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate operand id.
+ * @param nodes Graph node table.
+ * @param positive Mutable set for positive operands.
+ * @param negative Mutable set for negated operands.
+ */
+function rememberComplementValue(value, nodes, positive, negative) {
+    const negated = readNegatedValue(value, nodes);
+    if (negated !== undefined) {
+        if (isComplementSafe(negated, nodes)) {
+            negative.add(negated);
+        }
+        return;
+    }
+    if (isComplementSafe(value, nodes)) {
+        positive.add(value);
+    }
+}
+/**
+ * @brief Read the operand of a Not node.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param value Candidate node id.
+ * @param nodes Graph node table.
+ * @returns Inner node id for Not, otherwise undefined.
+ */
+function readNegatedValue(value, nodes) {
+    const node = nodes[value];
+    return node?.tag === NodeTag.Not ? node.value : undefined;
+}
+/**
+ * @brief Decide whether a node is safe for complement algebra.
+ * @details Only pure structural predicates are allowed. Nodes that inspect user
+ * predicates or nested graph execution stay out of `a`/`!a` folding.
+ * @param value Candidate node id.
+ * @param nodes Graph node table.
+ * @returns True when complement laws can be applied to the node.
+ */
+function isComplementSafe(value, nodes) {
+    const node = nodes[value];
+    if (node === undefined) {
+        return false;
+    }
+    switch (node.tag) {
+        case NodeTag.Const:
+            return typeof node.value === "boolean";
+        case NodeTag.IsString:
+        case NodeTag.IsNumber:
+        case NodeTag.IsBoolean:
+        case NodeTag.IsBigInt:
+        case NodeTag.IsSymbol:
+        case NodeTag.IsObject:
+        case NodeTag.IsArray:
+        case NodeTag.IsUndefined:
+        case NodeTag.IsNull:
+        case NodeTag.IsInteger:
+        case NodeTag.Equals:
+        case NodeTag.Gte:
+        case NodeTag.Lte:
+        case NodeTag.StringMin:
+        case NodeTag.StringMax:
+        case NodeTag.Regex:
+        case NodeTag.HasOwn:
+        case NodeTag.HasOwnData:
+        case NodeTag.StrictKeys:
+            return true;
+        case NodeTag.Not:
+            return isComplementSafe(node.value, nodes);
+        case NodeTag.And:
+        case NodeTag.Or:
+            return areComplementSafeValues(node.values, nodes);
+        default:
+            return false;
+    }
+}
+/**
+ * @brief Decide whether every value in a boolean fold is complement-safe.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ * @param values Operand ids from a nested fold.
+ * @param nodes Graph node table.
+ * @returns True when the whole nested fold can participate in complement laws.
+ */
+function areComplementSafeValues(values, nodes) {
+    for (let index = 0; index < values.length; index += 1) {
+        const value = values[index];
+        if (value === undefined || !isComplementSafe(value, nodes)) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/optimize/compact.d.ts

@@ -1,10 +1,17 @@
 /**
  * @file compact.ts
  * @brief Reachability compaction for optimized graphs.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import type { Graph } from "../ir/index.js";
 /**
- * @brief compact reachable.
+ * @brief Remove unreachable IR nodes and remap the remaining node ids densely.
+ * @details Earlier optimizer passes may leave replaced nodes in the arena so
+ * alias bookkeeping stays simple. This pass is the boundary that rewrites the
+ * graph back into the dense id space expected by codegen and public graph reads.
+ * @param graph Graph produced by earlier optimizer passes.
+ * @returns Graph containing only nodes reachable from entry and result.
  */
 export declare function compactReachable(graph: Graph): Graph;
 //# sourceMappingURL=compact.d.ts.map

package/dist/optimize/compact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../src/optimize/compact.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAqB,MAAM,gBAAgB,CAAC;AAG/D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAyBpD"}
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../src/optimize/compact.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAqB,MAAM,gBAAgB,CAAC;AAG/D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAyBpD"}

package/dist/optimize/compact.js

@@ -1,10 +1,17 @@
 /**
  * @file compact.ts
  * @brief Reachability compaction for optimized graphs.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
  */
 import { remapId, remapNode } from "./remap.js";
 /**
- * @brief compact reachable.
+ * @brief Remove unreachable IR nodes and remap the remaining node ids densely.
+ * @details Earlier optimizer passes may leave replaced nodes in the arena so
+ * alias bookkeeping stays simple. This pass is the boundary that rewrites the
+ * graph back into the dense id space expected by codegen and public graph reads.
+ * @param graph Graph produced by earlier optimizer passes.
+ * @returns Graph containing only nodes reachable from entry and result.
  */
 export function compactReachable(graph) {
     const reachable = markReachable(graph);
@@ -33,7 +40,11 @@ export function compactReachable(graph) {
     };
 }
 /**
- * @brief mark reachable.
+ * @brief Mark graph nodes reachable from the entry and result roots.
+ * @details The scan walks dependency edges with an explicit stack to avoid
+ * recursion limits on large generated schemas.
+ * @param graph Graph to scan.
+ * @returns Boolean reachability bitmap aligned with the original node table.
  */
 function markReachable(graph) {
     const reachable = new Array(graph.nodes.length).fill(false);

package/dist/optimize/domain.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file domain.ts
+ * @brief Validation-domain specialization for dispatch child graphs.
+ * @details Optimizer helpers preserve graph equivalence while shrinking redundant nodes
+ * before code generation consumes the graph.
+ */
+import type { Graph } from "../ir/index.js";
+/**
+ * @brief Specialize nested validation graphs with domain knowledge.
+ * @details Dispatch nodes already know the primitive domain of each child arm.
+ * This pass pushes that fact into child graphs so redundant type checks collapse.
+ * @param graph Root graph to specialize.
+ * @returns The original graph when no node changed, otherwise a rewritten graph.
+ */
+export declare function specializeDomains(graph: Graph): Graph;
+//# sourceMappingURL=domain.d.ts.map

package/dist/optimize/domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../src/optimize/domain.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAER,KAAK,EAIR,MAAM,gBAAgB,CAAC;AAiDxB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAsBrD"}