typesea 0.1.0 → 0.2.0

package/dist/compile/issue.js

@@ -1,28 +1,211 @@
 /**
  * @file compile/issue.ts
  * @brief Diagnostic issue source snippets.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 import { UUID_PATTERN } from "../schema/index.js";
 import { pushRegex, stringRef } from "./context.js";
 import { stringLiteral } from "./names.js";
 /**
  * @brief emit pattern issue.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Generated expression for the string value.
+ * @param path Generated expression for the current diagnostic path.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param regex Pattern used by the schema check.
+ * @param name Human-readable pattern name stored in the issue.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source that appends a pattern issue when the test fails.
  */
 export function emitPatternIssue(value, path, issues, regex, name, context) {
     const source = regex === UUID_PATTERN ? UUID_PATTERN : regex;
     const index = pushRegex(context, source);
     const access = `r[${String(index)}]`;
-    return `if(((${access}.lastIndex=0),!${access}.test(${value}))){${emitIssueExpr(issues, path, "expected_pattern", stringRef(context, name), stringLiteral("string"))}}`;
+    const test = regexNeedsLastIndexReset(source)
+        ? `((${access}.lastIndex=0),!${access}.test(${value}))`
+        : `!${access}.test(${value})`;
+    /*
+     * Pattern names live in the string side table. That keeps generated source
+     * stable even when users provide long or escaped pattern descriptions.
+     */
+    return `if(${test}){${emitIssueExpr(issues, path, "expected_pattern", stringRef(context, name), stringLiteral("string"))}}`;
+}
+/**
+ * @brief emit pattern issue at one appended path segment.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Generated expression for the string value.
+ * @param path Generated expression for the current diagnostic path.
+ * @param segmentExpression Generated expression for the appended segment.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param regex Pattern used by the schema check.
+ * @param name Human-readable pattern name stored in the issue.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source that appends a one-segment pattern issue.
+ */
+export function emitPatternIssueAtSegment(value, path, segmentExpression, issues, regex, name, context) {
+    const source = regex === UUID_PATTERN ? UUID_PATTERN : regex;
+    const index = pushRegex(context, source);
+    const access = `r[${String(index)}]`;
+    const test = regexNeedsLastIndexReset(source)
+        ? `((${access}.lastIndex=0),!${access}.test(${value}))`
+        : `!${access}.test(${value})`;
+    return `if(${test}){${emitIssueExprAtSegment(issues, path, segmentExpression, "expected_pattern", stringRef(context, name), stringLiteral("string"))}}`;
+}
+/**
+ * @brief emit pattern issue at two appended path segments.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Generated expression for the string value.
+ * @param path Generated expression for the current diagnostic path.
+ * @param firstSegmentExpression Generated expression for the first appended segment.
+ * @param secondSegmentExpression Generated expression for the second appended segment.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param regex Pattern used by the schema check.
+ * @param name Human-readable pattern name stored in the issue.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source that appends a two-segment pattern issue.
+ */
+export function emitPatternIssueAtTwoSegments(value, path, firstSegmentExpression, secondSegmentExpression, issues, regex, name, context) {
+    const source = regex === UUID_PATTERN ? UUID_PATTERN : regex;
+    const index = pushRegex(context, source);
+    const access = `r[${String(index)}]`;
+    const test = regexNeedsLastIndexReset(source)
+        ? `((${access}.lastIndex=0),!${access}.test(${value}))`
+        : `!${access}.test(${value})`;
+    return `if(${test}){${emitIssueExprAtTwoSegments(issues, path, firstSegmentExpression, secondSegmentExpression, "expected_pattern", stringRef(context, name), stringLiteral("string"))}}`;
+}
+/**
+ * @brief Decide whether a RegExp must be reset before generated testing.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param regex RegExp stored in the generated side table.
+ * @returns True for stateful global or sticky expressions.
+ */
+function regexNeedsLastIndexReset(regex) {
+    return regex.global || regex.sticky;
 }
 /**
  * @brief emit issue.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param code Issue code string.
+ * @param expected Expected type or condition text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source that appends an issue at the current path.
  */
 export function emitIssue(issues, path, code, expected, actualExpression) {
     return emitIssueExpr(issues, path, code, stringLiteral(expected), actualExpression);
 }
+/**
+ * @brief emit issue at one appended path segment.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param segmentExpression Generated expression for the appended segment.
+ * @param code Issue code string.
+ * @param expected Expected type or condition text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source that appends an issue under one extra segment.
+ */
+export function emitIssueAtSegment(issues, path, segmentExpression, code, expected, actualExpression) {
+    return emitIssueExprAtSegment(issues, path, segmentExpression, code, stringLiteral(expected), actualExpression);
+}
+/**
+ * @brief emit issue at two appended path segments.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param firstSegmentExpression Generated expression for the first appended segment.
+ * @param secondSegmentExpression Generated expression for the second appended segment.
+ * @param code Issue code string.
+ * @param expected Expected type or condition text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source that appends an issue under two extra segments.
+ */
+export function emitIssueAtTwoSegments(issues, path, firstSegmentExpression, secondSegmentExpression, code, expected, actualExpression) {
+    return emitIssueExprAtTwoSegments(issues, path, firstSegmentExpression, secondSegmentExpression, code, stringLiteral(expected), actualExpression);
+}
 /**
  * @brief emit issue expr.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param code Issue code string.
+ * @param expectedExpression Generated expression for expected text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source that appends an issue using expression operands.
  */
 export function emitIssueExpr(issues, path, code, expectedExpression, actualExpression) {
     return `q(${issues},${path},${stringLiteral(code)},${expectedExpression},${actualExpression});`;
 }
+/**
+ * @brief emit issue expr at one appended path segment.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param segmentExpression Generated expression for the appended segment.
+ * @param code Issue code string.
+ * @param expectedExpression Generated expression for expected text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source using the most compact one-segment issue helper.
+ */
+export function emitIssueExprAtSegment(issues, path, segmentExpression, code, expectedExpression, actualExpression) {
+    const stringIndex = readStringRefIndex(segmentExpression);
+    if (stringIndex !== undefined) {
+        /*
+         * q1s reuses the pre-frozen path segment cache for static string keys.
+         * Dynamic segments still go through q1 because their value is known only
+         * inside the generated validator.
+         */
+        return `q1s(${issues},${path},${stringIndex},${stringLiteral(code)},${expectedExpression},${actualExpression});`;
+    }
+    return `q1(${issues},${path},${segmentExpression},${stringLiteral(code)},${expectedExpression},${actualExpression});`;
+}
+/**
+ * @brief emit issue expr at two appended path segments.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param issues Generated expression for the diagnostic buffer.
+ * @param path Generated expression for the current diagnostic path.
+ * @param firstSegmentExpression Generated expression for the first appended segment.
+ * @param secondSegmentExpression Generated expression for the second appended segment.
+ * @param code Issue code string.
+ * @param expectedExpression Generated expression for expected text.
+ * @param actualExpression Generated expression for actual type text.
+ * @returns JavaScript source using the two-segment issue helper.
+ */
+export function emitIssueExprAtTwoSegments(issues, path, firstSegmentExpression, secondSegmentExpression, code, expectedExpression, actualExpression) {
+    return `q2(${issues},${path},${firstSegmentExpression},${secondSegmentExpression},${stringLiteral(code)},${expectedExpression},${actualExpression});`;
+}
+/**
+ * @brief Extract the numeric side-table index from a generated string reference.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param expression Candidate generated expression such as `u[3]`.
+ * @returns Index text when the expression is a plain string-table read.
+ */
+function readStringRefIndex(expression) {
+    if (!expression.startsWith("u[") || !expression.endsWith("]")) {
+        return undefined;
+    }
+    const value = expression.slice(2, -1);
+    if (value.length === 0) {
+        return undefined;
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 48 || code > 57) {
+            return undefined;
+        }
+    }
+    return value;
+}

package/dist/compile/names.d.ts

@@ -1,16 +1,26 @@
 /**
  * @file compile-names.ts
  * @brief Generated function-name and string literal helpers.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  *
  * @invariant User-provided names never enter generated source until they are
  * reduced to a strict-mode-safe identifier with a fixed length bound.
  */
 /**
- * @brief safe function name.
+ * @brief Convert a user supplied compile name into a strict-mode function id.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Requested public function name.
+ * @returns Identifier-safe, reserved-word-safe, bounded function name.
  */
 export declare function safeFunctionName(value: string): string;
 /**
- * @brief string literal.
+ * @brief Quote a string for generated JavaScript source.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Runtime string to embed.
+ * @returns JSON-escaped string literal source.
  */
 export declare function stringLiteral(value: string): string;
 //# sourceMappingURL=names.d.ts.map

package/dist/compile/names.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/compile/names.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYtD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/compile/names.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgBtD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/compile/names.js

@@ -1,13 +1,19 @@
 /**
  * @file compile-names.ts
  * @brief Generated function-name and string literal helpers.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  *
  * @invariant User-provided names never enter generated source until they are
  * reduced to a strict-mode-safe identifier with a fixed length bound.
  */
 const MAX_GENERATED_FUNCTION_NAME_LENGTH = 96;
 /**
- * @brief safe function name.
+ * @brief Convert a user supplied compile name into a strict-mode function id.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Requested public function name.
+ * @returns Identifier-safe, reserved-word-safe, bounded function name.
  */
 export function safeFunctionName(value) {
     const replaced = value.replace(/[^$_a-zA-Z0-9]/gu, "_");
@@ -17,19 +23,29 @@ export function safeFunctionName(value) {
     if (/^[$_a-zA-Z]/u.test(bounded) && !reservedFunctionNames.has(bounded)) {
         return bounded;
     }
+    /*
+     * Prefixing recovers names that start with a digit or collide with reserved
+     * words while keeping the final identifier under the same length cap.
+     */
     const prefixed = `_${bounded}`;
     return prefixed.length > MAX_GENERATED_FUNCTION_NAME_LENGTH
         ? prefixed.slice(0, MAX_GENERATED_FUNCTION_NAME_LENGTH)
         : prefixed;
 }
 /**
- * @brief string literal.
+ * @brief Quote a string for generated JavaScript source.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Runtime string to embed.
+ * @returns JSON-escaped string literal source.
  */
 export function stringLiteral(value) {
     return JSON.stringify(value);
 }
 /**
- * @brief reserved function names.
+ * @brief Strict-mode names that cannot be emitted as generated function ids.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 const reservedFunctionNames = new Set([
     "arguments",

package/dist/compile/predicate.d.ts

@@ -1,23 +1,47 @@
 /**
  * @file compile/predicate.ts
  * @brief Boolean validator source emitter.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 import { type Schema } from "../schema/index.js";
 import type { EmitContext } from "./types.js";
 /**
  * @brief emit function.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Schema represented by the predicate.
+ * @param context Shared code-generation context.
+ * @returns Generated predicate function name.
+ * @invariant The same schema object maps to one predicate function per bundle.
  */
 export declare function emitFunction(schema: Schema, context: EmitContext): string;
 /**
  * @brief emit functions.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Shared code-generation context with accumulated predicate sources.
+ * @returns Concatenated JavaScript function declarations.
  */
 export declare function emitFunctions(context: EmitContext): string;
 /**
  * @brief emit expression.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Schema represented by the expression.
+ * @param value Generated expression for the candidate value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript expression that evaluates to a boolean.
  */
 export declare function emitExpression(schema: Schema, value: string, context: EmitContext): string;
 /**
  * @brief emit union.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param options Union option schemas.
+ * @param value Generated expression for the candidate value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript expression for the union predicate.
  */
 export declare function emitUnion(options: readonly Schema[], value: string, context: EmitContext): string;
 //# sourceMappingURL=predicate.d.ts.map

package/dist/compile/predicate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../../src/compile/predicate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAO5B,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AAE9D;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CAczE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAU1D;AAsBD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACnB,MAAM,CA+CR;AA0PD;;GAEG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACnB,MAAM,CAYR"}
+{"version":3,"file":"predicate.d.ts","sourceRoot":"","sources":["../../src/compile/predicate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EAIH,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AAO5B,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CAkBzE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAU1D;AA4BD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACrB,MAAM,CAuDR;AAyUD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACrB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACrB,MAAM,CAYR"}

package/dist/compile/predicate.js

@@ -1,18 +1,30 @@
 /**
  * @file compile/predicate.ts
  * @brief Boolean validator source emitter.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  */
 import { NumberCheckTag, ObjectModeTag, PresenceTag, SchemaTag, StringCheckTag } from "../kind/index.js";
 import { UUID_PATTERN } from "../schema/index.js";
 import { pushLiteral, pushRegex, pushSchema, stringRef } from "./context.js";
 /**
  * @brief emit function.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Schema represented by the predicate.
+ * @param context Shared code-generation context.
+ * @returns Generated predicate function name.
+ * @invariant The same schema object maps to one predicate function per bundle.
  */
 export function emitFunction(schema, context) {
     const cached = context.functionNames.get(schema);
     if (cached !== undefined) {
         return cached;
     }
+    /*
+     * Register before body emission so recursive references can point at the
+     * function name even while its body is still under construction.
+     */
     const name = `p${String(context.functions.length)}`;
     const source = {
         name,
@@ -25,6 +37,10 @@ export function emitFunction(schema, context) {
 }
 /**
  * @brief emit functions.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param context Shared code-generation context with accumulated predicate sources.
+ * @returns Concatenated JavaScript function declarations.
  */
 export function emitFunctions(context) {
     const chunks = new Array(context.functions.length);
@@ -39,6 +55,12 @@ export function emitFunctions(context) {
 }
 /**
  * @brief emit body.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Schema represented by this predicate body.
+ * @param value Generated expression for the candidate value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source for a predicate function body.
  */
 function emitBody(schema, value, context) {
     switch (schema.tag) {
@@ -58,6 +80,12 @@ function emitBody(schema, value, context) {
 }
 /**
  * @brief emit expression.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Schema represented by the expression.
+ * @param value Generated expression for the candidate value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript expression that evaluates to a boolean.
  */
 export function emitExpression(schema, value, context) {
     switch (schema.tag) {
@@ -78,6 +106,10 @@ export function emitExpression(schema, value, context) {
         case SchemaTag.Literal:
             return `Object.is(${value},l[${String(pushLiteral(context, schema.value))}])`;
         case SchemaTag.Array:
+            /*
+             * Composite schemas get their own functions. That keeps deeply nested
+             * predicates readable to V8 and avoids duplicating loops at each use site.
+             */
             return `${emitFunction(schema, context)}(${value})`;
         case SchemaTag.Tuple:
             return `${emitFunction(schema, context)}(${value})`;
@@ -100,14 +132,29 @@ export function emitExpression(schema, value, context) {
             return emitExpression(schema.inner, value, context);
         case SchemaTag.Lazy:
         case SchemaTag.Refine:
+            /*
+             * User predicates and lazy resolution remain behind the runtime `d`
+             * helper because generated source cannot inline their behavior.
+             */
             return `d(${String(pushSchema(context, schema))},${value})`;
     }
 }
 /**
  * @brief emit array body.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param item Schema applied to each logical slot.
+ * @param value Generated expression for the array value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source for an array predicate body.
  */
 function emitArrayBody(item, value, context) {
     const itemFunction = emitFunction(item, context);
+    /*
+     * Descriptor reads block accessor-backed slots without executing getters.
+     * Holes are forwarded as undefined so optional item schemas keep normal JS
+     * sparse-array semantics.
+     */
     return [
         `if(!Array.isArray(${value}))return false;`,
         `for(let i=0;i<${value}.length;i+=1){`,
@@ -120,9 +167,19 @@ function emitArrayBody(item, value, context) {
 }
 /**
  * @brief emit record body.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param item Schema applied to each own enumerable string key.
+ * @param value Generated expression for the record value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript source for a record predicate body.
  */
 function emitRecordBody(item, value, context) {
     const itemFunction = emitFunction(item, context);
+    /*
+     * Object.keys intentionally ignores inherited and non-enumerable keys,
+     * matching TypeSea record semantics while keeping iteration predictable.
+     */
     return [
         `if(!o(${value}))return false;`,
         `const ks=Object.keys(${value});`,
@@ -137,6 +194,9 @@ function emitRecordBody(item, value, context) {
 /**
  * @brief emit tuple body.
  * @details Emits tuple validation as straight-line descriptor reads and early returns.
+ * @param items Tuple item schemas.
+ * @param value Generated expression for the tuple value.
+ * @param context Shared code-generation context.
  * @returns Generated tuple predicate body.
  */
 function emitTupleBody(items, value, context) {
@@ -150,6 +210,10 @@ function emitTupleBody(items, value, context) {
         }
         const descriptor = `d${String(index)}`;
         const itemValue = `v${String(index)}`;
+        /*
+         * Tuple arity is already checked above. Each index still needs descriptor
+         * validation because an accessor slot would execute user code if read.
+         */
         chunks.push(`const ${descriptor}=gp(${value},${String(index)});`, `if(${descriptor}!==undefined&&!h.call(${descriptor},"value"))return false;`, `const ${itemValue}=${descriptor}===undefined?undefined:${descriptor}.value;`, `if(!${emitExpression(item, itemValue, context)})return false;`);
     }
     chunks.push("return true;");
@@ -158,6 +222,9 @@ function emitTupleBody(items, value, context) {
 /**
  * @brief emit object body.
  * @details Emits object validation as Ajv-style straight-line code with local descriptor variables.
+ * @param schema Object schema to emit.
+ * @param value Generated expression for the object value.
+ * @param context Shared code-generation context.
  * @returns Generated object predicate body.
  */
 function emitObjectBody(schema, value, context) {
@@ -174,6 +241,10 @@ function emitObjectBody(schema, value, context) {
         const itemValue = `v${String(index)}`;
         chunks.push(`const ${descriptor}=gp(${value},${key});`);
         if (entry.presence === PresenceTag.Optional) {
+            /*
+             * Optional own accessors are rejected. A missing descriptor is valid,
+             * but an own non-data property at the key is still hostile input.
+             */
             chunks.push(`if(${descriptor}!==undefined){`, `if(!h.call(${descriptor},"value"))return false;`, `const ${itemValue}=${descriptor}.value;`, `if(!${emitExpression(entry.schema, itemValue, context)})return false;`, `}else if(h.call(${value},${key}))return false;`);
         }
         else {
@@ -186,6 +257,9 @@ function emitObjectBody(schema, value, context) {
 /**
  * @brief emit strict object key body.
  * @details Emits a low-allocation known-key check specialized for one object shape.
+ * @param schema Object schema with mode and entries.
+ * @param value Generated expression for the object value.
+ * @param context Shared code-generation context.
  * @returns Generated strict-key prelude, or an empty string for passthrough objects.
  */
 function emitStrictObjectKeyBody(schema, value, context) {
@@ -203,6 +277,10 @@ function emitStrictObjectKeyBody(schema, value, context) {
     if (comparisons.length === 0) {
         return `if(Reflect.ownKeys(${value}).length!==0)return false;`;
     }
+    /*
+     * Reflect.ownKeys is required for strict objects because symbol and
+     * non-enumerable extras are still extras.
+     */
     return [
         `const xs=Reflect.ownKeys(${value});`,
         "for(let i=0;i<xs.length;i+=1){",
@@ -214,6 +292,10 @@ function emitStrictObjectKeyBody(schema, value, context) {
 /**
  * @brief emit discriminated union body.
  * @details Emits discriminant selection once and dispatches to branch validators.
+ * @param key Discriminant property name.
+ * @param cases Closed discriminated union cases.
+ * @param value Generated expression for the candidate object.
+ * @param context Shared code-generation context.
  * @returns Generated discriminated-union predicate body.
  */
 function emitDiscriminatedUnionBody(key, cases, value, context) {
@@ -237,6 +319,12 @@ function emitDiscriminatedUnionBody(key, cases, value, context) {
 }
 /**
  * @brief emit string.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema String schema with scalar checks.
+ * @param value Generated expression for the candidate value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript expression for the string predicate.
  */
 function emitString(schema, value, context) {
     const parts = [`(typeof ${value}==="string")`];
@@ -265,13 +353,25 @@ function emitString(schema, value, context) {
 }
 /**
  * @brief emit number.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param schema Number schema with scalar checks.
+ * @param value Generated expression for the candidate value.
+ * @returns JavaScript expression for the number predicate.
  */
 function emitNumber(schema, value) {
-    const parts = [
-        `(typeof ${value}==="number")`,
-        `Number.isFinite(${value})`
-    ];
+    const integer = numberChecksRequireInteger(schema.checks);
+    const parts = integer
+        ? [`Number.isInteger(${value})`]
+        : [
+            `(typeof ${value}==="number")`,
+            `Number.isFinite(${value})`
+        ];
     const checks = schema.checks;
+    /*
+     * Number.isInteger already proves finite number, so integer schemas avoid
+     * emitting a separate typeof/finite pair.
+     */
     for (let index = 0; index < checks.length; index += 1) {
         const check = checks[index];
         if (check === undefined) {
@@ -279,7 +379,6 @@ function emitNumber(schema, value) {
         }
         switch (check.tag) {
             case NumberCheckTag.Integer:
-                parts.push(`Number.isInteger(${value})`);
                 break;
             case NumberCheckTag.Gte:
                 parts.push(`(${value}>=${String(check.value)})`);
@@ -291,8 +390,29 @@ function emitNumber(schema, value) {
     }
     return `(${parts.join("&&")})`;
 }
+/**
+ * @brief Test whether a number schema contains an integer constraint.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param checks Number check list.
+ * @returns True when Number.isInteger can replace the broader number guard.
+ */
+function numberChecksRequireInteger(checks) {
+    for (let index = 0; index < checks.length; index += 1) {
+        if (checks[index]?.tag === NumberCheckTag.Integer) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * @brief emit union.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param options Union option schemas.
+ * @param value Generated expression for the candidate value.
+ * @param context Shared code-generation context.
+ * @returns JavaScript expression for the union predicate.
  */
 export function emitUnion(options, value, context) {
     const parts = [];
@@ -309,6 +429,12 @@ export function emitUnion(options, value, context) {
 }
 /**
  * @brief emit regex.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Generated expression for the candidate string.
+ * @param regex Pattern to test.
+ * @param context Shared code-generation context.
+ * @returns JavaScript expression that resets lastIndex and tests the regex.
  */
 function emitRegex(value, regex, context) {
     const index = pushRegex(context, regex);