typesea 0.1.0 → 0.3.0

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 { ArrayCheckTag, DateCheckTag, NumberCheckTag, ObjectModeTag, PresenceTag, SchemaTag, StringCheckTag } from "../kind/index.js";
+import { EMAIL_PATTERN, IPV4_PATTERN, IPV6_PATTERN, ISO_DATETIME_PATTERN, ISO_DATE_PATTERN, ULID_PATTERN, URL_PATTERN, 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,15 +55,29 @@ 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) {
         case SchemaTag.Array:
-            return emitArrayBody(schema.item, value, context);
+            return emitArrayBody(schema, value, context);
         case SchemaTag.Tuple:
+            if (schema.rest !== undefined) {
+                return `return d(${String(pushSchema(context, schema))},${value});`;
+            }
             return emitTupleBody(schema.items, value, context);
         case SchemaTag.Record:
             return emitRecordBody(schema.value, value, context);
+        case SchemaTag.Map:
+        case SchemaTag.Set:
+        case SchemaTag.InstanceOf:
+        case SchemaTag.Property:
+            return `return d(${String(pushSchema(context, schema))},${value});`;
         case SchemaTag.Object:
             return emitObjectBody(schema, value, context);
         case SchemaTag.DiscriminatedUnion:
@@ -58,6 +88,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) {
@@ -69,6 +105,8 @@ export function emitExpression(schema, value, context) {
             return emitString(schema, value, context);
         case SchemaTag.Number:
             return emitNumber(schema, value);
+        case SchemaTag.Date:
+            return emitDate(schema, value);
         case SchemaTag.BigInt:
             return `(typeof ${value}==="bigint")`;
         case SchemaTag.Symbol:
@@ -78,11 +116,23 @@ 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:
+            if (schema.rest !== undefined) {
+                return `d(${String(pushSchema(context, schema))},${value})`;
+            }
             return `${emitFunction(schema, context)}(${value})`;
         case SchemaTag.Record:
             return `${emitFunction(schema, context)}(${value})`;
+        case SchemaTag.Map:
+        case SchemaTag.Set:
+        case SchemaTag.InstanceOf:
+        case SchemaTag.Property:
+            return `d(${String(pushSchema(context, schema))},${value})`;
         case SchemaTag.Object:
             return `${emitFunction(schema, context)}(${value})`;
         case SchemaTag.Union:
@@ -100,16 +150,61 @@ 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 a Date predicate expression.
+ * @param schema Date schema with normalized checks.
+ * @param value Generated expression for the candidate value.
+ * @returns JavaScript expression that accepts valid Date objects within bounds.
+ */
+function emitDate(schema, value) {
+    const checks = schema.checks;
+    const parts = [
+        `(${value} instanceof Date)`,
+        `dg(${value})`
+    ];
+    for (let index = 0; index < checks.length; index += 1) {
+        const check = checks[index];
+        if (check === undefined) {
+            continue;
+        }
+        switch (check.tag) {
+            case DateCheckTag.Min:
+                parts.push(`dt(${value})>=${String(check.value)}`);
+                break;
+            case DateCheckTag.Max:
+                parts.push(`dt(${value})<=${String(check.value)}`);
+                break;
+        }
+    }
+    return `(${parts.join("&&")})`;
+}
 /**
  * @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) {
+function emitArrayBody(schema, value, context) {
+    const item = schema.item;
     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;`,
+        emitArrayLengthBody(value, schema.checks),
         `for(let i=0;i<${value}.length;i+=1){`,
         `const d=gp(${value},i);`,
         `if(d!==undefined&&!h.call(d,"value"))return false;`,
@@ -118,11 +213,49 @@ function emitArrayBody(item, value, context) {
         "return true;"
     ].join("");
 }
+/**
+ * @brief Emit array length checks for direct predicate bodies.
+ * @param value Generated expression for the candidate array.
+ * @param checks Normalized array length checks.
+ * @returns Straight-line early-return checks, or an empty string.
+ */
+function emitArrayLengthBody(value, checks) {
+    if (checks.length === 0) {
+        return "";
+    }
+    const chunks = [];
+    for (let index = 0; index < checks.length; index += 1) {
+        const check = checks[index];
+        if (check === undefined) {
+            chunks.push("return false;");
+            continue;
+        }
+        switch (check.tag) {
+            case ArrayCheckTag.Min:
+                chunks.push(`if(${value}.length<${String(check.value)})return false;`);
+                break;
+            case ArrayCheckTag.Max:
+                chunks.push(`if(${value}.length>${String(check.value)})return false;`);
+                break;
+        }
+    }
+    return chunks.join("");
+}
 /**
  * @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 +270,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 +286,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 +298,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,22 +317,54 @@ 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 {
             chunks.push(`if(${descriptor}===undefined||!h.call(${descriptor},"value"))return false;`, `const ${itemValue}=${descriptor}.value;`, `if(!${emitExpression(entry.schema, itemValue, context)})return false;`);
         }
     }
+    chunks.push(emitObjectCatchallBody(schema, value, context));
     chunks.push("return true;");
     return chunks.join("");
 }
+/**
+ * @brief Emit catchall checks for undeclared object keys.
+ * @param schema Object schema with optional catchall.
+ * @param value Generated expression for the object value.
+ * @param context Shared code-generation context.
+ * @returns Generated source that validates extra own keys.
+ */
+function emitObjectCatchallBody(schema, value, context) {
+    if (schema.catchall === undefined) {
+        return "";
+    }
+    const keys = schema.keys;
+    const membership = keyMembershipExpression("key", keys, context);
+    return [
+        `const cx=Reflect.ownKeys(${value});`,
+        "for(let ci=0;ci<cx.length;ci+=1){",
+        "const key=cx[ci];",
+        `if(typeof key==="string"&&${membership})continue;`,
+        `const cd=gp(${value},key);`,
+        "if(cd===undefined||!h.call(cd,\"value\"))return false;",
+        `if(!${emitExpression(schema.catchall, "cd.value", context)})return false;`,
+        "}"
+    ].join("");
+}
 /**
  * @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) {
-    if (schema.mode !== ObjectModeTag.Strict) {
+    if (schema.mode !== ObjectModeTag.Strict || schema.catchall !== undefined) {
         return "";
     }
     const entries = schema.entries;
@@ -203,6 +378,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 +393,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 +420,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")`];
@@ -259,19 +448,52 @@ function emitString(schema, value, context) {
             case StringCheckTag.Uuid:
                 parts.push(emitRegex(value, UUID_PATTERN, context));
                 break;
+            case StringCheckTag.Email:
+                parts.push(emitRegex(value, EMAIL_PATTERN, context));
+                break;
+            case StringCheckTag.Url:
+                parts.push(emitRegex(value, URL_PATTERN, context));
+                break;
+            case StringCheckTag.IsoDate:
+                parts.push(emitRegex(value, ISO_DATE_PATTERN, context));
+                break;
+            case StringCheckTag.IsoDateTime:
+                parts.push(emitRegex(value, ISO_DATETIME_PATTERN, context));
+                break;
+            case StringCheckTag.Ulid:
+                parts.push(emitRegex(value, ULID_PATTERN, context));
+                break;
+            case StringCheckTag.Ipv4:
+                parts.push(emitRegex(value, IPV4_PATTERN, context));
+                break;
+            case StringCheckTag.Ipv6:
+                parts.push(emitRegex(value, IPV6_PATTERN, context));
+                break;
         }
     }
     return `(${parts.join("&&")})`;
 }
 /**
  * @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 +501,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)})`);
@@ -287,12 +508,42 @@ function emitNumber(schema, value) {
             case NumberCheckTag.Lte:
                 parts.push(`(${value}<=${String(check.value)})`);
                 break;
+            case NumberCheckTag.Gt:
+                parts.push(`(${value}>${String(check.value)})`);
+                break;
+            case NumberCheckTag.Lt:
+                parts.push(`(${value}<${String(check.value)})`);
+                break;
+            case NumberCheckTag.MultipleOf:
+                parts.push(`(${value}%${String(check.value)}===0)`);
+                break;
         }
     }
     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,9 +560,35 @@ 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);
     const access = `r[${String(index)}]`;
     return `((${access}.lastIndex=0),${access}.test(${value}))`;
 }
+/**
+ * @brief Emit a side-table backed key membership expression.
+ * @param key Generated expression containing the candidate property key.
+ * @param keys Known object shape keys.
+ * @param context Shared code-generation context.
+ * @returns JavaScript expression that is true for known string keys.
+ */
+function keyMembershipExpression(key, keys, context) {
+    if (keys.length === 0) {
+        return "false";
+    }
+    const parts = new Array(keys.length);
+    for (let index = 0; index < keys.length; index += 1) {
+        const value = keys[index];
+        parts[index] = value === undefined
+            ? "false"
+            : `${key}===${stringRef(context, value)}`;
+    }
+    return `(${parts.join("||")})`;
+}

package/dist/compile/runtime.d.ts

@@ -1,55 +1,142 @@
 /**
  * @file compile-runtime.ts
  * @brief Runtime support passed into generated validator factories.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
  *
  * @section side_tables Side-table ABI
  * Generated validators receive literals, regexps, keysets, strings, and
  * dynamic schema fallbacks as indexed tables. The emitted source contains only
  * numeric table slots and compact helper names.
  */
-import type { Issue, PathSegment } from "../issue/index.js";
+import type { CheckResult, Issue, PathSegment } from "../issue/index.js";
 import type { LiteralValue, Schema } from "../schema/index.js";
 /**
- * @brief boolean predicate.
+ * @brief Allocation-lean validator root generated for `is` calls.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Candidate runtime value.
+ * @returns True when the generated predicate accepts the value.
  */
 export type BooleanPredicate = (value: unknown) => boolean;
 /**
- * @brief issue collector root.
+ * @brief Diagnostic collector generated for `check` calls.
+ * @details Generated collectors return undefined for the successful fast path.
+ * Hand-written collectors still have to return an issue array and are validated
+ * before publication.
+ * @param value Candidate runtime value.
+ * @returns Undefined on success, otherwise the collected validation issues.
  */
-export type IssueCollectorRoot = (value: unknown) => readonly Issue[];
+export type IssueCollectorRoot = (value: unknown) => readonly Issue[] | undefined;
 /**
- * @brief dynamic check.
+ * @brief Result-producing wrapper generated beside every compiled predicate.
+ * @details Generated-source helpers keep the side-table ABI and JavaScript source shape
+ * stable across runtime and AOT emission.
+ * @param value Candidate runtime value.
+ * @returns TypeSea check result carrying the accepted value or issue list.
+ */
+export type CheckResultRoot = (value: unknown) => CheckResult<unknown>;
+/**
+ * @brief Boolean fallback for schemas that cannot be fully lowered.
+ * @details Generated code stores only a schema table index. The helper keeps
+ * recursive and user-refined branches out of the emitted source while retaining
+ * the same boolean contract as the interpreter.
+ * @param schemaIndex Slot in the side table supplied to the factory.
+ * @param value Candidate value for that schema.
+ * @returns True when the fallback schema accepts the value.
  */
 export type DynamicCheck = (schemaIndex: number, value: unknown) => boolean;
 /**
- * @brief dynamic issue check.
+ * @brief Diagnostic fallback for non-lowered schema fragments.
+ * @details The generated collector delegates here only at opaque graph leaves.
+ * Nested issues are copied into the caller-owned buffer so the outer generated
+ * path prefix remains in control.
+ * @param schemaIndex Slot in the side table supplied to the factory.
+ * @param value Candidate value for that schema.
+ * @param path Path prefix owned by the generated collector.
+ * @param issues Mutable issue buffer owned by the caller.
  */
 export type DynamicIssueCheck = (schemaIndex: number, value: unknown, path: readonly PathSegment[], issues: Issue[]) => void;
 /**
- * @brief strict keys check.
+ * @brief First-fault fallback for non-lowered schema fragments.
+ * @details Opaque lazy and refine schemas use the interpreter for correctness,
+ * then return only the first nested issue under the generated path prefix.
+ * @param schemaIndex Slot in the side table supplied to the factory.
+ * @param value Candidate value for that schema.
+ * @param path Path prefix owned by the generated collector.
+ * @returns First nested issue, or undefined when the fallback accepts the value.
+ */
+export type DynamicFirstIssueCheck = (schemaIndex: number, value: unknown, path: readonly PathSegment[]) => Issue | undefined;
+/**
+ * @brief Runtime helper for strict-object excess key validation.
+ * @details Code generation can choose safe or fast property access strategies,
+ * but strict key counting remains centralized so the emitted source uses a
+ * compact ABI.
+ * @param value Candidate object.
+ * @param keys Allowed string keys for the strict schema.
+ * @returns True when no extra own string key is present.
  */
 export type StrictKeysCheck = (value: unknown, keys: readonly string[]) => boolean;
 /**
- * @brief runtime bundle.
+ * @brief Published validator entry points returned by a compiled factory.
+ * @details The three functions share side tables and generated helper code but
+ * expose the distinct public contracts used by Guard methods.
  */
 export interface RuntimeBundle {
     readonly is: BooleanPredicate;
     readonly check: IssueCollectorRoot;
+    readonly result: CheckResultRoot;
+    readonly first: CheckResultRoot;
 }
 /**
- * @brief is factory.
+ * @brief Factory signature consumed by `new Function` compiled modules.
+ * @details Generated source is pure JavaScript text. All runtime objects that
+ * should not be serialized into source travel through these side tables, which
+ * keeps emitted code small and friendly to V8 inline caches.
+ * @param literals Literal constants referenced by emitted predicates.
+ * @param regexps Precompiled regular expressions for string constraints.
+ * @param keysets Strict-object key tables.
+ * @param strings Shared string constants used by generated diagnostics.
+ * @param dynamicCheck Boolean fallback for opaque schema fragments.
+ * @param dynamicIssueCheck Diagnostic fallback for opaque schema fragments.
+ * @param strictKeys Shared strict-object excess key helper.
+ * @returns Runtime bundle exposed by the compiled guard.
  */
-export type IsFactory = (literals: readonly LiteralValue[], regexps: readonly RegExp[], keysets: readonly (readonly string[])[], strings: readonly string[], dynamicCheck: DynamicCheck, dynamicIssueCheck: DynamicIssueCheck, strictKeys: StrictKeysCheck) => RuntimeBundle;
+export type IsFactory = (literals: readonly LiteralValue[], regexps: readonly RegExp[], keysets: readonly (readonly string[])[], strings: readonly string[], dynamicCheck: DynamicCheck, dynamicIssueCheck: DynamicIssueCheck, dynamicFirstIssueCheck: DynamicFirstIssueCheck, strictKeys: StrictKeysCheck) => RuntimeBundle;
 /**
- * @brief make dynamic check.
+ * @brief Build the boolean fallback table reader for generated validators.
+ * @details Missing table slots fail closed. That preserves the security
+ * invariant that malformed generated code cannot accidentally accept a value by
+ * indexing outside the schema side table.
+ * @param schemas Schema side table captured by the compiled guard.
+ * @returns Boolean fallback callback used by emitted predicates.
  */
 export declare function makeDynamicCheck(schemas: readonly Schema[]): DynamicCheck;
 /**
- * @brief make dynamic issue check.
+ * @brief Build the diagnostic fallback table reader for generated validators.
+ * @details Nested interpreter issues are re-rooted under the path supplied by
+ * generated code. This lets compiled object and array checks delegate complex
+ * children without losing exact issue locations.
+ * @param schemas Schema side table captured by the compiled guard.
+ * @returns Issue fallback callback used by emitted collectors.
  */
 export declare function makeDynamicIssueCheck(schemas: readonly Schema[]): DynamicIssueCheck;
 /**
- * @brief strict keys.
+ * @brief Build the first-fault fallback table reader for generated validators.
+ * @details This path is entered only for opaque schema fragments that codegen
+ * cannot inline. The nested interpreter result is re-rooted once and returned.
+ * @param schemas Schema side table captured by the compiled guard.
+ * @returns First-issue fallback callback used by emitted collectors.
+ */
+export declare function makeDynamicFirstIssueCheck(schemas: readonly Schema[]): DynamicFirstIssueCheck;
+/**
+ * @brief Safe strict-object key membership helper for generated validators.
+ * @details The default compiled mode uses Reflect.ownKeys so symbol and
+ * non-enumerable extras are rejected as strictly as the interpreter. Unsafe
+ * modes may emit a cheaper loop, but this helper remains the conservative ABI.
+ * @param value Candidate object value.
+ * @param keys Allowed string keys for the strict object schema.
+ * @returns True when every own key belongs to the schema key set.
  */
 export declare function strictKeys(value: unknown, keys: readonly string[]): boolean;
 //# sourceMappingURL=runtime.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/compile/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,KAAK,EAAE,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE5E;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,MAAM,EAAE,KAAK,EAAE,KACZ,IAAI,CAAC;AAEV;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,MAAM,EAAE,KACpB,OAAO,CAAC;AAEb;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACvC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,YAAY,EAAE,YAAY,EAC1B,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,eAAe,KACxB,aAAa,CAAC;AAEnB;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,CAKzE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,iBAAiB,CA6BnB;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAYT"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/compile/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,KAAK,EAAE,GAAG,SAAS,CAAC;AAElF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,WAAW,CAAC,OAAO,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAE5E;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC5B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,MAAM,EAAE,KAAK,EAAE,KACd,IAAI,CAAC;AAEV;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACjC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,WAAW,EAAE,KAC3B,KAAK,GAAG,SAAS,CAAC;AAEvB;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAC1B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,MAAM,EAAE,KACtB,OAAO,CAAC;AAEb;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACnC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,SAAS,GAAG,CACpB,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACvC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,YAAY,EAAE,YAAY,EAC1B,iBAAiB,EAAE,iBAAiB,EACpC,sBAAsB,EAAE,sBAAsB,EAC9C,UAAU,EAAE,eAAe,KAC1B,aAAa,CAAC;AAEnB;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,CAKzE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,SAAS,MAAM,EAAE,GAC3B,iBAAiB,CA8BnB;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACtC,OAAO,EAAE,SAAS,MAAM,EAAE,GAC3B,sBAAsB,CA2BxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACtB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,MAAM,EAAE,GACxB,OAAO,CAYT"}