typesea 0.1.0 → 0.2.0

package/dist/plan/schema-predicate.js

@@ -1,12 +1,16 @@
 /**
  * @file schema-predicate.ts
  * @brief Schema-specialized predicate kernels for validation plans.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 import { NumberCheckTag, ObjectModeTag, PresenceTag, SchemaTag, StringCheckTag } from "../kind/index.js";
-import { UUID_PATTERN, resolveLazySchema } from "../schema/index.js";
-import { findDiscriminatedUnionCase, hasObjectKey, isDataPropertyDescriptor, isPlainRecord, readOwnDataProperty } from "../evaluate/shared.js";
+import { UUID_PATTERN, resolveLazySchema, schemaCanAcceptUndefined } from "../schema/index.js";
+import { findDiscriminatedUnionCase, hasObjectKey, isArrayIndexKey, isDataPropertyDescriptor, isPlainRecord, readOwnDataProperty } from "../evaluate/shared.js";
 /**
  * @brief execute schema kernel.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 export function executeSchemaKernel(schema, value, state, runChild) {
     switch (schema.tag) {
@@ -56,7 +60,12 @@ export function executeSchemaKernel(schema, value, state, runChild) {
     }
 }
 /**
- * @brief is string schema.
+ * @brief Execute a string schema against one runtime value.
+ * @param schema String schema with normalized checks.
+ * @param value Candidate runtime value.
+ * @returns True when the value is a string and every string check passes.
+ * @details Regex state is reset around each test so global or sticky patterns do
+ * not leak `lastIndex` across validation calls.
  */
 function isStringSchema(schema, value) {
     if (typeof value !== "string") {
@@ -98,7 +107,12 @@ function isStringSchema(schema, value) {
     return true;
 }
 /**
- * @brief is number schema.
+ * @brief Execute a number schema against one runtime value.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param schema Number schema with normalized checks.
+ * @param value Candidate runtime value.
+ * @returns True when the value is finite and satisfies every numeric check.
  */
 function isNumberSchema(schema, value) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -131,12 +145,26 @@ function isNumberSchema(schema, value) {
     return true;
 }
 /**
- * @brief is array schema.
+ * @brief Execute array validation with sparse-slot semantics.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param item Schema applied to each logical array slot.
+ * @param value Candidate value supplied by the caller.
+ * @param state Shared recursion and cycle state.
+ * @param runChild Dispatcher for nested schema predicates.
+ * @returns True when the value satisfies the array schema.
  */
 function isArraySchema(item, value, state, runChild) {
     if (!Array.isArray(value)) {
         return false;
     }
+    if (schemaCanAcceptUndefined(item)) {
+        /*
+         * Undefined-valid item schemas make holes valid. Use the present-index
+         * walker so sparse arrays do not pay for absent slots.
+         */
+        return isPresentArraySchema(item, value, state, runChild);
+    }
     for (let index = 0; index < value.length; index += 1) {
         const property = readArrayIndexDataProperty(value, index);
         if (property === null ||
@@ -147,7 +175,42 @@ function isArraySchema(item, value, state, runChild) {
     return true;
 }
 /**
- * @brief is tuple schema.
+ * @brief Validate only present indexes for undefined-accepting item schemas.
+ * @details Skips holes only when `undefined` is already accepted by the item schema.
+ * @param item Schema applied to each present own index.
+ * @param value Array already proven by the caller.
+ * @param state Shared recursion and cycle state.
+ * @param runChild Dispatcher for nested schema predicates.
+ * @returns True when every present own index satisfies the item schema.
+ */
+function isPresentArraySchema(item, value, state, runChild) {
+    const keys = Object.getOwnPropertyNames(value);
+    for (let keyIndex = 0; keyIndex < keys.length; keyIndex += 1) {
+        const key = keys[keyIndex];
+        if (key === undefined || !isArrayIndexKey(key, value.length)) {
+            continue;
+        }
+        /*
+         * Accessor-backed present indexes are rejected here because reading them
+         * would run user code and break the safe validation boundary.
+         */
+        const property = readArrayKeyDataProperty(value, key);
+        if (property === null ||
+            (property !== undefined && !runChild(item, property.value, state))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * @brief Execute fixed-arity tuple validation.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param items Schema for each tuple index.
+ * @param value Candidate runtime value.
+ * @param state Shared recursion and cycle state.
+ * @param runChild Dispatcher for nested schema predicates.
+ * @returns True when length and every indexed item match exactly.
  */
 function isTupleSchema(items, value, state, runChild) {
     if (!Array.isArray(value) || value.length !== items.length) {
@@ -165,10 +228,26 @@ function isTupleSchema(items, value, state, runChild) {
     return true;
 }
 /**
- * @brief read array index data property.
+ * @brief Read one tuple or dense-array index through a descriptor.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Array being inspected.
+ * @param index Numeric index.
+ * @returns Data descriptor, undefined for a hole, or null for an accessor slot.
  */
 function readArrayIndexDataProperty(value, index) {
-    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    return readArrayKeyDataProperty(value, String(index));
+}
+/**
+ * @brief Read one canonical array index key without executing accessors.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param value Array being inspected.
+ * @param key Canonical array index key.
+ * @returns Data descriptor, undefined for a hole, or null for an accessor slot.
+ */
+function readArrayKeyDataProperty(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
     if (descriptor === undefined) {
         return undefined;
     }
@@ -178,7 +257,8 @@ function readArrayIndexDataProperty(value, index) {
     return descriptor;
 }
 /**
- * @brief is record schema.
+ * @brief Check record schema.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function isRecordSchema(item, value, state, runChild) {
     if (!isPlainRecord(value)) {
@@ -198,7 +278,15 @@ function isRecordSchema(item, value, state, runChild) {
     return true;
 }
 /**
- * @brief is object schema.
+ * @brief Execute object schema validation.
+ * @param schema Object schema with ordered entries and strict-mode lookup.
+ * @param value Candidate runtime value.
+ * @param state Shared recursion and cycle state.
+ * @param runChild Dispatcher for nested property schemas.
+ * @returns True when required/optional fields and strict-key rules pass.
+ * @details Required properties are read through descriptors. In strict mode, the
+ * all-required path can compare own key counts; optional shapes must inspect
+ * each key so extra symbol or undeclared string keys fail closed.
  */
 function isObjectSchema(schema, value, state, runChild) {
     if (!isPlainRecord(value)) {
@@ -243,7 +331,14 @@ function isObjectSchema(schema, value, state, runChild) {
     return true;
 }
 /**
- * @brief is union schema.
+ * @brief Execute a general union by probing options in order.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param options Union option schemas.
+ * @param value Candidate runtime value.
+ * @param state Shared recursion and cycle state.
+ * @param runChild Dispatcher for nested option schemas.
+ * @returns True when at least one option accepts the value.
  */
 function isUnionSchema(options, value, state, runChild) {
     for (let index = 0; index < options.length; index += 1) {
@@ -255,7 +350,15 @@ function isUnionSchema(options, value, state, runChild) {
     return false;
 }
 /**
- * @brief is discriminated union schema.
+ * @brief Execute a discriminated union through its tag field.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
+ * @param key Discriminant property name.
+ * @param cases Closed case table.
+ * @param value Candidate runtime value.
+ * @param state Shared recursion and cycle state.
+ * @param runChild Dispatcher for selected case schema.
+ * @returns True when the discriminant is a string and the selected case passes.
  */
 function isDiscriminatedUnionSchema(key, cases, value, state, runChild) {
     if (!isPlainRecord(value)) {
@@ -270,7 +373,8 @@ function isDiscriminatedUnionSchema(key, cases, value, state, runChild) {
     return selected !== undefined && runChild(selected, value, state);
 }
 /**
- * @brief is strict true.
+ * @brief Check strict true.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 function isStrictTrue(value) {
     return value === true;

package/dist/plan/types.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file types.ts
  * @brief Optimized validation plan contracts.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 import type { Graph } from "../ir/index.js";
 import type { Schema } from "../schema/index.js";

package/dist/plan/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plan/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plan/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACrC"}

package/dist/plan/types.js

@@ -1,5 +1,7 @@
 /**
  * @file types.ts
  * @brief Optimized validation plan contracts.
+ * @details Plan helpers keep schema-specialized execution aligned with optimized IR while
+ * preserving interpreter parity.
  */
 export {};

package/dist/result/index.d.ts

@@ -1,27 +1,41 @@
 /**
- * @brief result.
+ * @brief Explicit success-or-failure value used instead of implicit exceptions.
+ * @details Public validators return Result so failure is visible in the type
+ * system and callers must handle diagnostics deliberately.
  */
 export type Result<TValue, TError> = Ok<TValue> | Err<TError>;
 /**
- * @brief ok.
+ * @brief Successful Result variant.
+ * @details The payload is named `value` so consumers can destructure success
+ * without colliding with the failure-side `error` field.
  */
 export interface Ok<TValue> {
     readonly ok: true;
     readonly value: TValue;
 }
 /**
- * @brief err.
+ * @brief Failed Result variant.
+ * @details Errors remain typed payloads rather than thrown control flow, which
+ * keeps validation and decoding APIs predictable under composition.
  */
 export interface Err<TError> {
     readonly ok: false;
     readonly error: TError;
 }
 /**
- * @brief ok.
+ * @brief Construct a frozen successful Result.
+ * @details Result helpers keep success and failure explicit in value space instead of
+ * relying on implicit control flow.
+ * @param value Value produced by a successful operation.
+ * @returns Immutable success variant.
  */
 export declare function ok<TValue>(value: TValue): Result<TValue, never>;
 /**
- * @brief err.
+ * @brief Construct a frozen failed Result.
+ * @details Result helpers keep success and failure explicit in value space instead of
+ * relying on implicit control flow.
+ * @param error Typed failure payload.
+ * @returns Immutable failure variant.
  */
 export declare function err<TError>(error: TError): Result<never, TError>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/result/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,IAC7B,EAAE,CAAC,MAAM,CAAC,GACV,GAAG,CAAC,MAAM,CAAC,CAAC;AAEhB;;GAEG;AACH,MAAM,WAAW,EAAE,CAAC,MAAM;IACxB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,GAAG,CAAC,MAAM;IACzB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAM/D;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAMhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/result/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,IAC3B,EAAE,CAAC,MAAM,CAAC,GACV,GAAG,CAAC,MAAM,CAAC,CAAC;AAElB;;;;GAIG;AACH,MAAM,WAAW,EAAE,CAAC,MAAM;IACtB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,GAAG,CAAC,MAAM;IACvB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAM/D;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAMhE"}

package/dist/result/index.js

@@ -1,5 +1,9 @@
 /**
- * @brief ok.
+ * @brief Construct a frozen successful Result.
+ * @details Result helpers keep success and failure explicit in value space instead of
+ * relying on implicit control flow.
+ * @param value Value produced by a successful operation.
+ * @returns Immutable success variant.
  */
 export function ok(value) {
     const result = {
@@ -9,7 +13,11 @@ export function ok(value) {
     return Object.freeze(result);
 }
 /**
- * @brief err.
+ * @brief Construct a frozen failed Result.
+ * @details Result helpers keep success and failure explicit in value space instead of
+ * relying on implicit control flow.
+ * @param error Typed failure payload.
+ * @returns Immutable failure variant.
  */
 export function err(error) {
     const result = {

package/dist/schema/common.d.ts

@@ -1,30 +1,93 @@
 /**
  * @file schema/common.ts
  * @brief Private schema shape predicates.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 import type { ObjectKeyLookup } from "./types.js";
 /**
- * @brief is record.
+ * @brief Sentinel for a missing own data slot.
+ * @details `undefined` is a valid schema literal, so absence needs a distinct
+ * value that cannot collide with user-authored schema data.
+ */
+declare const missingDataProperty: unique symbol;
+/**
+ * @brief Test whether a schema field read observed the sentinel.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ * @param value Candidate field value returned by readOwnDataProperty.
+ * @returns True when the caller must treat the schema field as absent.
+ */
+export declare function isMissingDataProperty(value: unknown): value is typeof missingDataProperty;
+/**
+ * @brief Check that an object owns a concrete data descriptor.
+ * @param value Object whose descriptor table is being inspected.
+ * @param key Field name or symbol.
+ * @returns True only when the field exists directly on the object as data.
+ * @details Schema records are consumed across public boundaries. Descriptor
+ * reads avoid invoking accessors and avoid accepting prototype-backed fields.
+ */
+export declare function hasOwnDataProperty(value: object, key: PropertyKey): boolean;
+/**
+ * @brief Read one own schema data slot without consulting the prototype chain.
+ * @param value Object carrying a schema record.
+ * @param key Field name or symbol to read.
+ * @returns The stored value, or the missing-data sentinel.
+ * @details Callers must not use bracket reads on untrusted schema-like objects:
+ * a forged prototype getter could execute code or change validation meaning.
+ */
+export declare function readOwnDataProperty(value: object, key: PropertyKey): unknown;
+/**
+ * @brief Accept object records suitable for schema metadata traversal.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ * @param value Candidate schema record.
+ * @returns True for non-array objects whose own fields are all data slots.
  */
 export declare function isRecord(value: unknown): value is Readonly<Record<string, unknown>>;
 /**
- * @brief is unknown array.
+ * @brief Accept dense arrays whose slots can be read without side effects.
+ * @param value Candidate schema vector.
+ * @returns True for arrays with only own data descriptors and no holes.
+ * @details Schema vectors such as `checks`, `entries`, and `options` are arena
+ * metadata. Holes and inherited slots would make validation depend on array
+ * prototype state, so they are rejected at the boundary.
  */
 export declare function isUnknownArray(value: unknown): value is readonly unknown[];
 /**
- * @brief is plain reg exp.
+ * @brief Accept only unmodified RegExp instances in schema records.
+ * @param value Candidate pattern object.
+ * @returns True for a plain RegExp with no own behavioral overrides.
+ * @details Regex checks are copied into generated and interpreted validators.
+ * Rejecting own overrides prevents later mutation of `exec`, `test`, `source`,
+ * or `flags` from changing stored schema behavior.
  */
 export declare function isPlainRegExp(value: unknown): value is RegExp;
 /**
- * @brief is string array.
+ * @brief Validate a dense vector of object shape keys.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ * @param value Candidate key vector.
+ * @returns True when every slot is a string.
  */
 export declare function isStringArray(value: unknown): value is readonly string[];
 /**
- * @brief is object key lookup.
+ * @brief Validate the O(1) lookup table paired with object schema keys.
+ * @param value Candidate null or plain object lookup.
+ * @param keys Ordered key vector from the same object schema.
+ * @returns True when the lookup contains exactly the listed keys mapped to true.
+ * @details The lookup and key vector must agree so strict-object validation can
+ * reject extra keys without rebuilding a membership set at runtime.
  */
 export declare function isObjectKeyLookup(value: unknown, keys: readonly string[]): value is ObjectKeyLookup;
 /**
- * @brief includes string.
+ * @brief Linear membership check for short schema-owned string vectors.
+ * @param values Trusted frozen vector.
+ * @param value Candidate string.
+ * @returns True when the candidate appears in the vector.
+ * @details These vectors are small and validation-time only; a loop avoids
+ * allocating transient Set objects while preserving deterministic order.
  */
 export declare function includesString(values: readonly string[], value: string): boolean;
+export {};
 //# sourceMappingURL=common.d.ts.map

package/dist/schema/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/schema/common.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAKnF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,OAAO,EAAE,CAE1E;AAyBD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAO7D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,MAAM,EAAE,CAUxE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,KAAK,IAAI,eAAe,CAqB1B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOhF"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/schema/common.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,QAAA,MAAM,mBAAmB,eAAwC,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACjC,KAAK,EAAE,OAAO,GACf,KAAK,IAAI,OAAO,mBAAmB,CAErC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,WAAW,GACjB,OAAO,CAIT;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,WAAW,GACjB,OAAO,CAOT;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAKnF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,OAAO,EAAE,CAI1E;AA2CD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAO7D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,MAAM,EAAE,CAUxE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,SAAS,MAAM,EAAE,GACxB,KAAK,IAAI,eAAe,CAqB1B;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOhF"}

package/dist/schema/common.js

@@ -1,9 +1,60 @@
 /**
  * @file schema/common.ts
  * @brief Private schema shape predicates.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 /**
- * @brief is record.
+ * @brief Sentinel for a missing own data slot.
+ * @details `undefined` is a valid schema literal, so absence needs a distinct
+ * value that cannot collide with user-authored schema data.
+ */
+const missingDataProperty = Symbol("typesea.missingDataProperty");
+/**
+ * @brief Test whether a schema field read observed the sentinel.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ * @param value Candidate field value returned by readOwnDataProperty.
+ * @returns True when the caller must treat the schema field as absent.
+ */
+export function isMissingDataProperty(value) {
+    return value === missingDataProperty;
+}
+/**
+ * @brief Check that an object owns a concrete data descriptor.
+ * @param value Object whose descriptor table is being inspected.
+ * @param key Field name or symbol.
+ * @returns True only when the field exists directly on the object as data.
+ * @details Schema records are consumed across public boundaries. Descriptor
+ * reads avoid invoking accessors and avoid accepting prototype-backed fields.
+ */
+export function hasOwnDataProperty(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor !== undefined &&
+        Object.prototype.hasOwnProperty.call(descriptor, "value");
+}
+/**
+ * @brief Read one own schema data slot without consulting the prototype chain.
+ * @param value Object carrying a schema record.
+ * @param key Field name or symbol to read.
+ * @returns The stored value, or the missing-data sentinel.
+ * @details Callers must not use bracket reads on untrusted schema-like objects:
+ * a forged prototype getter could execute code or change validation meaning.
+ */
+export function readOwnDataProperty(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined ||
+        !Object.prototype.hasOwnProperty.call(descriptor, "value")) {
+        return missingDataProperty;
+    }
+    return descriptor.value;
+}
+/**
+ * @brief Accept object records suitable for schema metadata traversal.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ * @param value Candidate schema record.
+ * @returns True for non-array objects whose own fields are all data slots.
  */
 export function isRecord(value) {
     return typeof value === "object" &&
@@ -12,14 +63,23 @@ export function isRecord(value) {
         hasOnlyDataProperties(value);
 }
 /**
- * @brief is unknown array.
+ * @brief Accept dense arrays whose slots can be read without side effects.
+ * @param value Candidate schema vector.
+ * @returns True for arrays with only own data descriptors and no holes.
+ * @details Schema vectors such as `checks`, `entries`, and `options` are arena
+ * metadata. Holes and inherited slots would make validation depend on array
+ * prototype state, so they are rejected at the boundary.
  */
 export function isUnknownArray(value) {
-    return Array.isArray(value) && hasOnlyDataProperties(value);
+    return Array.isArray(value) &&
+        hasOnlyDataProperties(value) &&
+        hasDenseDataSlots(value);
 }
 /**
- * @brief has only data properties.
- * @details Rejects accessor descriptors before schema internals read fields by key.
+ * @brief Reject accessor descriptors before schema internals read fields.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ * @param value Object whose own descriptor table is inspected.
  * @returns True when every own property is backed by a data slot.
  */
 function hasOnlyDataProperties(value) {
@@ -40,7 +100,27 @@ function hasOnlyDataProperties(value) {
     return true;
 }
 /**
- * @brief is plain reg exp.
+ * @brief Require array indexes from 0 to length - 1 to be own data slots.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ * @param value Candidate schema vector.
+ * @returns True when no sparse or prototype-backed index is present.
+ */
+function hasDenseDataSlots(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        if (!hasOwnDataProperty(value, String(index))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * @brief Accept only unmodified RegExp instances in schema records.
+ * @param value Candidate pattern object.
+ * @returns True for a plain RegExp with no own behavioral overrides.
+ * @details Regex checks are copied into generated and interpreted validators.
+ * Rejecting own overrides prevents later mutation of `exec`, `test`, `source`,
+ * or `flags` from changing stored schema behavior.
  */
 export function isPlainRegExp(value) {
     return value instanceof RegExp &&
@@ -51,7 +131,11 @@ export function isPlainRegExp(value) {
         !Object.prototype.hasOwnProperty.call(value, "flags");
 }
 /**
- * @brief is string array.
+ * @brief Validate a dense vector of object shape keys.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ * @param value Candidate key vector.
+ * @returns True when every slot is a string.
  */
 export function isStringArray(value) {
     if (!isUnknownArray(value)) {
@@ -65,7 +149,12 @@ export function isStringArray(value) {
     return true;
 }
 /**
- * @brief is object key lookup.
+ * @brief Validate the O(1) lookup table paired with object schema keys.
+ * @param value Candidate null or plain object lookup.
+ * @param keys Ordered key vector from the same object schema.
+ * @returns True when the lookup contains exactly the listed keys mapped to true.
+ * @details The lookup and key vector must agree so strict-object validation can
+ * reject extra keys without rebuilding a membership set at runtime.
  */
 export function isObjectKeyLookup(value, keys) {
     if (!isRecord(value)) {
@@ -77,7 +166,7 @@ export function isObjectKeyLookup(value, keys) {
     }
     for (let index = 0; index < keys.length; index += 1) {
         const key = keys[index];
-        if (key === undefined || value[key] !== true) {
+        if (key === undefined || readOwnDataProperty(value, key) !== true) {
             return false;
         }
     }
@@ -90,7 +179,12 @@ export function isObjectKeyLookup(value, keys) {
     return true;
 }
 /**
- * @brief includes string.
+ * @brief Linear membership check for short schema-owned string vectors.
+ * @param values Trusted frozen vector.
+ * @param value Candidate string.
+ * @returns True when the candidate appears in the vector.
+ * @details These vectors are small and validation-time only; a loop avoids
+ * allocating transient Set objects while preserving deterministic order.
  */
 export function includesString(values, value) {
     for (let index = 0; index < values.length; index += 1) {

package/dist/schema/freeze.d.ts

@@ -1,10 +1,14 @@
 /**
  * @file schema/freeze.ts
  * @brief Schema freezing and collection hardening.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 import type { Schema } from "./types.js";
 /**
  * @brief freeze schema.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 export declare function freezeSchema(schema: Schema): Schema;
 //# sourceMappingURL=freeze.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"freeze.d.ts","sourceRoot":"","sources":["../../src/schema/freeze.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAGV,MAAM,EAGP,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"freeze.d.ts","sourceRoot":"","sources":["../../src/schema/freeze.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAGR,MAAM,EAGT,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD"}