typesea 0.1.0 → 0.3.0

package/dist/json-schema/emit-scalar.d.ts

@@ -1,25 +1,48 @@
 /**
  * @file emit-scalar.ts
  * @brief Scalar TypeSea schema to JSON Schema emitters.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { SchemaTag } from "../kind/index.js";
 import type { PathSegment } from "../issue/index.js";
 import { type LiteralValue, type Schema } from "../schema/index.js";
 import type { JsonSchema, JsonSchemaExportIssue } from "./types.js";
 /**
- * @brief emit string.
+ * @brief Emit TypeSea string checks into JSON Schema string keywords.
+ * @details Repeated min and max checks collapse to the strongest bounds.
+ * Regular expressions are emitted only when their flags can be preserved by the
+ * JSON Schema `pattern` keyword; unsupported flags are reported as issues.
+ * @param schema String schema to emit.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @returns JSON Schema string object.
  */
 export declare function emitString(schema: Extract<Schema, {
     readonly tag: typeof SchemaTag.String;
 }>, path: PathSegment[], issues: JsonSchemaExportIssue[]): JsonSchema;
 /**
- * @brief emit number.
+ * @brief Emit TypeSea number checks into JSON Schema number keywords.
+ * @details Integer checks narrow the emitted type, while finite lower and upper
+ * bounds collapse to the strongest minimum and maximum. Non-finite bounds are
+ * rejected because JSON Schema cannot preserve them portably.
+ * @param schema Number schema to emit.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @returns JSON Schema number object, or undefined when bounds are unsupported.
  */
 export declare function emitNumber(schema: Extract<Schema, {
     readonly tag: typeof SchemaTag.Number;
 }>, path: PathSegment[], issues: JsonSchemaExportIssue[]): JsonSchema | undefined;
 /**
- * @brief emit literal.
+ * @brief Emit a literal schema as a JSON Schema `const` value.
+ * @details Only JSON-compatible literals are accepted. Undefined, bigint,
+ * symbol, NaN, infinity, and negative zero have no faithful JSON Schema literal
+ * encoding, so they become export issues instead of weakened output.
+ * @param value Literal value carried by the TypeSea schema.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @returns JSON Schema const object, or undefined for unsupported literals.
  */
 export declare function emitLiteral(value: LiteralValue, path: PathSegment[], issues: JsonSchemaExportIssue[]): JsonSchema | undefined;
 //# sourceMappingURL=emit-scalar.d.ts.map

package/dist/json-schema/emit-scalar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit-scalar.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-scalar.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEL,SAAS,EAEV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAC9B,UAAU,CAkCZ;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAC9B,UAAU,GAAG,SAAS,CAiCxB;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAC9B,UAAU,GAAG,SAAS,CAyBxB"}
+{"version":3,"file":"emit-scalar.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-scalar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEH,SAAS,EAEZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAMH,KAAK,YAAY,EACjB,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EACR,UAAU,EACV,qBAAqB,EAExB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACtB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAChC,UAAU,CAiEZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACtB,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,SAAS,CAAC,MAAM,CAAA;CAAE,CAAC,EAClE,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAChC,UAAU,GAAG,SAAS,CA8DxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACvB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,GAChC,UAAU,GAAG,SAAS,CAyBxB"}

package/dist/json-schema/emit-scalar.js

@@ -1,15 +1,25 @@
 /**
  * @file emit-scalar.ts
  * @brief Scalar TypeSea schema to JSON Schema emitters.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { NumberCheckTag, SchemaTag, StringCheckTag } from "../kind/index.js";
-import { UUID_PATTERN } from "../schema/index.js";
+import { IPV4_PATTERN, IPV6_PATTERN, ISO_DATETIME_PATTERN, ISO_DATE_PATTERN, UUID_PATTERN } from "../schema/index.js";
 import { pushJsonSchemaIssue } from "./issue.js";
 /**
- * @brief emit string.
+ * @brief Emit TypeSea string checks into JSON Schema string keywords.
+ * @details Repeated min and max checks collapse to the strongest bounds.
+ * Regular expressions are emitted only when their flags can be preserved by the
+ * JSON Schema `pattern` keyword; unsupported flags are reported as issues.
+ * @param schema String schema to emit.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @returns JSON Schema string object.
  */
 export function emitString(schema, path, issues) {
     const result = { type: "string" };
+    const patterns = [];
     const checks = schema.checks;
     for (let index = 0; index < checks.length; index += 1) {
         const check = checks[index];
@@ -18,29 +28,66 @@ export function emitString(schema, path, issues) {
         }
         switch (check.tag) {
             case StringCheckTag.Min:
-                result.minLength = check.value;
+                result.minLength = result.minLength === undefined
+                    ? check.value
+                    : Math.max(result.minLength, check.value);
                 break;
             case StringCheckTag.Max:
-                result.maxLength = check.value;
+                result.maxLength = result.maxLength === undefined
+                    ? check.value
+                    : Math.min(result.maxLength, check.value);
                 break;
             case StringCheckTag.Regex:
                 if (check.regex.flags.length !== 0) {
                     pushJsonSchemaIssue(path, issues, "unsupported_regex_flags", "JSON Schema pattern cannot preserve RegExp flags");
                 }
                 else {
-                    result.pattern = check.regex.source;
+                    patterns.push(check.regex.source);
                 }
                 break;
             case StringCheckTag.Uuid:
                 result.format = "uuid";
-                result.pattern = UUID_PATTERN.source;
+                patterns.push(UUID_PATTERN.source);
+                break;
+            case StringCheckTag.Email:
+                result.format = "email";
+                break;
+            case StringCheckTag.Url:
+                result.format = "uri";
+                break;
+            case StringCheckTag.IsoDate:
+                result.format = "date";
+                patterns.push(ISO_DATE_PATTERN.source);
+                break;
+            case StringCheckTag.IsoDateTime:
+                result.format = "date-time";
+                patterns.push(ISO_DATETIME_PATTERN.source);
+                break;
+            case StringCheckTag.Ulid:
+                patterns.push("^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$");
+                break;
+            case StringCheckTag.Ipv4:
+                result.format = "ipv4";
+                patterns.push(IPV4_PATTERN.source);
+                break;
+            case StringCheckTag.Ipv6:
+                result.format = "ipv6";
+                patterns.push(IPV6_PATTERN.source);
                 break;
         }
     }
+    appendStringPatterns(result, patterns);
     return result;
 }
 /**
- * @brief emit number.
+ * @brief Emit TypeSea number checks into JSON Schema number keywords.
+ * @details Integer checks narrow the emitted type, while finite lower and upper
+ * bounds collapse to the strongest minimum and maximum. Non-finite bounds are
+ * rejected because JSON Schema cannot preserve them portably.
+ * @param schema Number schema to emit.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @returns JSON Schema number object, or undefined when bounds are unsupported.
  */
 export function emitNumber(schema, path, issues) {
     const before = issues.length;
@@ -60,7 +107,9 @@ export function emitNumber(schema, path, issues) {
                     pushJsonSchemaIssue(path, issues, "unsupported_number_bound", "Number bounds must be finite");
                 }
                 else {
-                    result.minimum = check.value;
+                    result.minimum = result.minimum === undefined
+                        ? check.value
+                        : Math.max(result.minimum, check.value);
                 }
                 break;
             case NumberCheckTag.Lte:
@@ -68,7 +117,37 @@ export function emitNumber(schema, path, issues) {
                     pushJsonSchemaIssue(path, issues, "unsupported_number_bound", "Number bounds must be finite");
                 }
                 else {
-                    result.maximum = check.value;
+                    result.maximum = result.maximum === undefined
+                        ? check.value
+                        : Math.min(result.maximum, check.value);
+                }
+                break;
+            case NumberCheckTag.Gt:
+                if (!Number.isFinite(check.value)) {
+                    pushJsonSchemaIssue(path, issues, "unsupported_number_bound", "Number bounds must be finite");
+                }
+                else {
+                    result.exclusiveMinimum = result.exclusiveMinimum === undefined
+                        ? check.value
+                        : Math.max(result.exclusiveMinimum, check.value);
+                }
+                break;
+            case NumberCheckTag.Lt:
+                if (!Number.isFinite(check.value)) {
+                    pushJsonSchemaIssue(path, issues, "unsupported_number_bound", "Number bounds must be finite");
+                }
+                else {
+                    result.exclusiveMaximum = result.exclusiveMaximum === undefined
+                        ? check.value
+                        : Math.min(result.exclusiveMaximum, check.value);
+                }
+                break;
+            case NumberCheckTag.MultipleOf:
+                if (!Number.isFinite(check.value) || check.value <= 0) {
+                    pushJsonSchemaIssue(path, issues, "unsupported_number_bound", "multipleOf must be positive and finite");
+                }
+                else {
+                    result.multipleOf = result.multipleOf ?? check.value;
                 }
                 break;
         }
@@ -79,7 +158,14 @@ export function emitNumber(schema, path, issues) {
     return result;
 }
 /**
- * @brief emit literal.
+ * @brief Emit a literal schema as a JSON Schema `const` value.
+ * @details Only JSON-compatible literals are accepted. Undefined, bigint,
+ * symbol, NaN, infinity, and negative zero have no faithful JSON Schema literal
+ * encoding, so they become export issues instead of weakened output.
+ * @param value Literal value carried by the TypeSea schema.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @returns JSON Schema const object, or undefined for unsupported literals.
  */
 export function emitLiteral(value, path, issues) {
     if (value === undefined) {
@@ -102,3 +188,31 @@ export function emitLiteral(value, path, issues) {
     }
     return { const: value };
 }
+/**
+ * @brief Append JSON Schema pattern constraints without weakening repeated checks.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
+ * @param result Mutable string schema output.
+ * @param patterns Ordered TypeSea pattern sources.
+ * @post One pattern stays inline; multiple patterns become an `allOf` chain.
+ */
+function appendStringPatterns(result, patterns) {
+    if (patterns.length === 0) {
+        return;
+    }
+    if (patterns.length === 1) {
+        const pattern = patterns[0];
+        if (pattern !== undefined) {
+            result.pattern = pattern;
+        }
+        return;
+    }
+    const schemas = new Array(patterns.length);
+    for (let index = 0; index < patterns.length; index += 1) {
+        const pattern = patterns[index];
+        if (pattern !== undefined) {
+            schemas[index] = { pattern };
+        }
+    }
+    result.allOf = schemas;
+}

package/dist/json-schema/emit-types.d.ts

@@ -1,12 +1,22 @@
 /**
  * @file emit-types.ts
  * @brief Internal JSON Schema emitter contracts.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import type { PathSegment } from "../issue/index.js";
 import type { Schema } from "../schema/index.js";
 import type { JsonSchema, JsonSchemaDialect, JsonSchemaExportIssue } from "./types.js";
 /**
- * @brief json schema emitter.
+ * @brief Recursive emitter callback shared by JSON Schema emitter modules.
+ * @details Child emitters receive the same path stack and issue buffer as their
+ * parent, which avoids allocating intermediate diagnostic collections during a
+ * deep schema walk.
+ * @param schema Schema node to convert.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param dialect Target JSON Schema dialect.
+ * @returns JSON Schema fragment, boolean schema, or undefined on failure.
  */
 export type JsonSchemaEmitter = (schema: Schema, path: PathSegment[], issues: JsonSchemaExportIssue[], dialect: JsonSchemaDialect) => JsonSchema | undefined;
 //# sourceMappingURL=emit-types.d.ts.map

package/dist/json-schema/emit-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit-types.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,OAAO,EAAE,iBAAiB,KACvB,UAAU,GAAG,SAAS,CAAC"}
+{"version":3,"file":"emit-types.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EACR,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,OAAO,EAAE,iBAAiB,KACzB,UAAU,GAAG,SAAS,CAAC"}

package/dist/json-schema/emit-types.js

@@ -1,5 +1,7 @@
 /**
  * @file emit-types.ts
  * @brief Internal JSON Schema emitter contracts.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 export {};

package/dist/json-schema/emit.d.ts

@@ -1,12 +1,23 @@
 /**
  * @file emit.ts
  * @brief TypeSea schema to JSON Schema emitter dispatcher.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import type { PathSegment } from "../issue/index.js";
 import type { Schema } from "../schema/index.js";
 import type { JsonSchema, JsonSchemaDialect, JsonSchemaExportIssue } from "./types.js";
 /**
- * @brief emit schema.
+ * @brief Dispatch one TypeSea schema node to the matching JSON Schema emitter.
+ * @details Unsupported runtime-only features are reported as structured export
+ * issues instead of being erased. That fail-closed policy prevents the exporter
+ * from producing a schema that appears equivalent while accepting a different
+ * value set.
+ * @param schema Schema node currently being emitted.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param dialect Target JSON Schema dialect.
+ * @returns JSON Schema fragment, boolean schema, or undefined on failure.
  */
 export declare function emitSchema(schema: Schema, path: PathSegment[], issues: JsonSchemaExportIssue[], dialect: JsonSchemaDialect): JsonSchema | undefined;
 //# sourceMappingURL=emit.d.ts.map

package/dist/json-schema/emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAmBjD,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,OAAO,EAAE,iBAAiB,GACzB,UAAU,GAAG,SAAS,CA2DxB"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/json-schema/emit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAmBjD,OAAO,KAAK,EACR,UAAU,EACV,iBAAiB,EACjB,qBAAqB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,EAAE,EACnB,MAAM,EAAE,qBAAqB,EAAE,EAC/B,OAAO,EAAE,iBAAiB,GAC3B,UAAU,GAAG,SAAS,CAyExB"}

package/dist/json-schema/emit.js

@@ -1,6 +1,8 @@
 /**
  * @file emit.ts
  * @brief TypeSea schema to JSON Schema emitter dispatcher.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { SchemaTag } from "../kind/index.js";
 import { emitDiscriminatedUnion, emitIntersection, emitNullable, emitUnion } from "./emit-combinator.js";
@@ -8,7 +10,16 @@ import { emitArray, emitObject, emitRecord, emitTuple } from "./emit-composite.j
 import { emitLiteral, emitNumber, emitString } from "./emit-scalar.js";
 import { pushJsonSchemaIssue } from "./issue.js";
 /**
- * @brief emit schema.
+ * @brief Dispatch one TypeSea schema node to the matching JSON Schema emitter.
+ * @details Unsupported runtime-only features are reported as structured export
+ * issues instead of being erased. That fail-closed policy prevents the exporter
+ * from producing a schema that appears equivalent while accepting a different
+ * value set.
+ * @param schema Schema node currently being emitted.
+ * @param path Mutable issue path stack owned by the export walk.
+ * @param issues Mutable export issue buffer.
+ * @param dialect Target JSON Schema dialect.
+ * @returns JSON Schema fragment, boolean schema, or undefined on failure.
  */
 export function emitSchema(schema, path, issues, dialect) {
     switch (schema.tag) {
@@ -20,6 +31,9 @@ export function emitSchema(schema, path, issues, dialect) {
             return emitString(schema, path, issues);
         case SchemaTag.Number:
             return emitNumber(schema, path, issues);
+        case SchemaTag.Date:
+            pushJsonSchemaIssue(path, issues, "unsupported_date", "JSON Schema cannot represent JavaScript Date objects");
+            return undefined;
         case SchemaTag.BigInt:
             pushJsonSchemaIssue(path, issues, "unsupported_bigint", "JSON Schema has no bigint type");
             return undefined;
@@ -31,11 +45,17 @@ export function emitSchema(schema, path, issues, dialect) {
         case SchemaTag.Literal:
             return emitLiteral(schema.value, path, issues);
         case SchemaTag.Array:
-            return emitArray(schema.item, path, issues, emitSchema, dialect);
+            return emitArray(schema, path, issues, emitSchema, dialect);
         case SchemaTag.Tuple:
-            return emitTuple(schema.items, path, issues, emitSchema, dialect);
+            return emitTuple(schema, path, issues, emitSchema, dialect);
         case SchemaTag.Record:
             return emitRecord(schema.value, path, issues, emitSchema, dialect);
+        case SchemaTag.Map:
+        case SchemaTag.Set:
+        case SchemaTag.InstanceOf:
+        case SchemaTag.Property:
+            pushJsonSchemaIssue(path, issues, "unsupported_runtime_object", "JSON Schema cannot preserve this JavaScript runtime object contract");
+            return undefined;
         case SchemaTag.Object:
             return emitObject(schema, path, issues, emitSchema, dialect);
         case SchemaTag.Union:

package/dist/json-schema/freeze.d.ts

@@ -1,14 +1,25 @@
 /**
  * @file freeze.ts
  * @brief Immutable JSON Schema export results.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import type { JsonSchema, JsonSchemaExportIssue } from "./types.js";
 /**
- * @brief freeze json schema.
+ * @brief Deep-freeze a JSON Schema export result before publication.
+ * @details Exported schemas may be shared across framework adapters. Freezing
+ * prevents later mutation from changing validation semantics after a schema was
+ * handed to another subsystem.
+ * @param schema JSON Schema fragment or boolean schema.
+ * @returns The same schema value after recursive hardening.
  */
 export declare function freezeJsonSchema(schema: JsonSchema): JsonSchema;
 /**
- * @brief freeze json schema issues.
+ * @brief Freeze JSON Schema export issues and their path arrays.
+ * @details Paths are mutable during traversal for stack efficiency, then frozen
+ * at the boundary so callers cannot rewrite diagnostic locations later.
+ * @param issues Export issues collected during emission.
+ * @returns The same issue array after recursive hardening.
  */
 export declare function freezeJsonSchemaIssues(issues: readonly JsonSchemaExportIssue[]): readonly JsonSchemaExportIssue[];
 //# sourceMappingURL=freeze.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"freeze.d.ts","sourceRoot":"","sources":["../../src/json-schema/freeze.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAK/D;AA8GD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,qBAAqB,EAAE,GACvC,SAAS,qBAAqB,EAAE,CASlC"}
+{"version":3,"file":"freeze.d.ts","sourceRoot":"","sources":["../../src/json-schema/freeze.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACR,UAAU,EACV,qBAAqB,EAExB,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAK/D;AAoID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,SAAS,qBAAqB,EAAE,GACzC,SAAS,qBAAqB,EAAE,CASlC"}

package/dist/json-schema/freeze.js

@@ -1,9 +1,16 @@
 /**
  * @file freeze.ts
  * @brief Immutable JSON Schema export results.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 /**
- * @brief freeze json schema.
+ * @brief Deep-freeze a JSON Schema export result before publication.
+ * @details Exported schemas may be shared across framework adapters. Freezing
+ * prevents later mutation from changing validation semantics after a schema was
+ * handed to another subsystem.
+ * @param schema JSON Schema fragment or boolean schema.
+ * @returns The same schema value after recursive hardening.
  */
 export function freezeJsonSchema(schema) {
     if (typeof schema === "boolean") {
@@ -12,7 +19,13 @@ export function freezeJsonSchema(schema) {
     return freezeJsonSchemaInner(schema, new WeakSet());
 }
 /**
- * @brief freeze json schema inner.
+ * @brief Recursively freeze one object-shaped JSON Schema fragment.
+ * @details A WeakSet protects against repeated references introduced by callers
+ * or future emitters. Current emission is tree-shaped, but this guard keeps the
+ * hardener robust at the module boundary.
+ * @param schema Object-shaped JSON Schema fragment.
+ * @param frozen Objects already processed by this hardening walk.
+ * @returns The same object after nested values are frozen.
  */
 function freezeJsonSchemaInner(schema, frozen) {
     if (frozen.has(schema)) {
@@ -52,8 +65,12 @@ function freezeJsonSchemaInner(schema, frozen) {
     return Object.freeze(schema);
 }
 /**
- * @brief freeze json schema items.
- * @details Handles both homogeneous `items` schemas and draft-07 tuple item arrays.
+ * @brief Freeze the dialect-dependent `items` payload.
+ * @details Draft-07 tuple output stores an array under `items`, while newer
+ * dialects use object-shaped homogeneous item schemas. Both representations are
+ * hardened here before the parent schema is frozen.
+ * @param items JSON Schema `items` payload to harden.
+ * @param frozen Objects already processed by this hardening walk.
  */
 function freezeJsonSchemaItems(items, frozen) {
     if (Array.isArray(items)) {
@@ -64,7 +81,11 @@ function freezeJsonSchemaItems(items, frozen) {
     freezeJsonSchemaValue(schema, frozen);
 }
 /**
- * @brief freeze json schema value.
+ * @brief Freeze one nested JSON Schema value when it is object-shaped.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
+ * @param schema Boolean or object-shaped JSON Schema fragment.
+ * @param frozen Objects already processed by this hardening walk.
  */
 function freezeJsonSchemaValue(schema, frozen) {
     if (typeof schema !== "boolean") {
@@ -72,7 +93,11 @@ function freezeJsonSchemaValue(schema, frozen) {
     }
 }
 /**
- * @brief freeze json schema array.
+ * @brief Freeze an array of nested schema fragments.
+ * @details Elements are hardened before the array itself so no mutable child is
+ * reachable through the frozen container.
+ * @param schemas Array of JSON Schema fragments.
+ * @param frozen Objects already processed by this hardening walk.
  */
 function freezeJsonSchemaArray(schemas, frozen) {
     for (let index = 0; index < schemas.length; index += 1) {
@@ -84,7 +109,11 @@ function freezeJsonSchemaArray(schemas, frozen) {
     Object.freeze(schemas);
 }
 /**
- * @brief freeze json schema properties.
+ * @brief Freeze an object-property schema table.
+ * @details Property tables are traversed by own enumerable keys because JSON
+ * Schema object maps are data dictionaries, not prototype-based classes.
+ * @param properties Property-name to schema table.
+ * @param frozen Objects already processed by this hardening walk.
  */
 function freezeJsonSchemaProperties(properties, frozen) {
     const keys = Object.keys(properties);
@@ -100,7 +129,11 @@ function freezeJsonSchemaProperties(properties, frozen) {
     Object.freeze(properties);
 }
 /**
- * @brief freeze json schema issues.
+ * @brief Freeze JSON Schema export issues and their path arrays.
+ * @details Paths are mutable during traversal for stack efficiency, then frozen
+ * at the boundary so callers cannot rewrite diagnostic locations later.
+ * @param issues Export issues collected during emission.
+ * @returns The same issue array after recursive hardening.
  */
 export function freezeJsonSchemaIssues(issues) {
     for (let index = 0; index < issues.length; index += 1) {

package/dist/json-schema/index.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public JSON Schema export module.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { type AsyncDecoder } from "../async/index.js";
 import { type Decoder } from "../decoder/index.js";
@@ -10,11 +12,23 @@ import type { Schema } from "../schema/index.js";
 import type { JsonSchema, JsonSchemaExportIssue, JsonSchemaOptions } from "./types.js";
 export type { JsonSchema, JsonSchemaDialect, JsonSchemaExportCode, JsonSchemaExportIssue, JsonSchemaObject, JsonSchemaOptions, JsonSchemaPrimitive, JsonSchemaTypeName } from "./types.js";
 /**
- * @brief to json schema.
+ * @brief Export the schema behind a guard or decoder as JSON Schema.
+ * @details Decoder values are rejected before emission because transform logic
+ * has no lossless JSON Schema representation. This keeps the exporter honest:
+ * it returns a schema only when the runtime validator can be expressed without
+ * hidden TypeSea execution.
+ * @param guard Guard or decoder value provided by public callers.
+ * @param options Optional dialect and schema id configuration.
+ * @returns Export result with either a frozen JSON Schema document or issues.
  */
 export declare function toJsonSchema<TValue>(guard: Guard<TValue, Presence> | Decoder<TValue> | AsyncDecoder<TValue>, options?: Partial<JsonSchemaOptions>): Result<JsonSchema, readonly JsonSchemaExportIssue[]>;
 /**
- * @brief schema to json schema.
+ * @brief Export a raw TypeSea schema into a JSON Schema document.
+ * @details This internal-facing helper skips guard extraction but still routes
+ * through the same emitter and issue accumulator as the public guard API.
+ * @param schema Schema value that already passed TypeSea construction checks.
+ * @param options Optional dialect and schema id configuration.
+ * @returns Export result with a frozen JSON Schema document or diagnostics.
  */
 export declare function schemaToJsonSchema(schema: Schema, options?: Partial<JsonSchemaOptions>): Result<JsonSchema, readonly JsonSchemaExportIssue[]>;
 //# sourceMappingURL=index.d.ts.map

package/dist/json-schema/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/json-schema/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAajD,OAAO,KAAK,EACV,UAAU,EAEV,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EACjC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,EACvE,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACnC,MAAM,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC,CAsBtD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACnC,MAAM,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC,CAEtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/json-schema/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAajD,OAAO,KAAK,EACR,UAAU,EAEV,qBAAqB,EACrB,iBAAiB,EACpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACR,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EACrB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAC/B,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,EACvE,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACrC,MAAM,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC,CAsBtD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACrC,MAAM,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC,CAEtD"}

package/dist/json-schema/index.js

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public JSON Schema export module.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import { isAsyncDecoderValue } from "../async/index.js";
 import { isDecoderValue } from "../decoder/index.js";
@@ -9,7 +11,14 @@ import { emitSchema } from "./emit.js";
 import { freezeJsonSchema, freezeJsonSchemaIssues } from "./freeze.js";
 import { JSON_SCHEMA_2020_12_ID, JSON_SCHEMA_DRAFT_07_ID, readJsonSchemaGuardSchema, readJsonSchemaOptions, readJsonSchemaSchema } from "./read.js";
 /**
- * @brief to json schema.
+ * @brief Export the schema behind a guard or decoder as JSON Schema.
+ * @details Decoder values are rejected before emission because transform logic
+ * has no lossless JSON Schema representation. This keeps the exporter honest:
+ * it returns a schema only when the runtime validator can be expressed without
+ * hidden TypeSea execution.
+ * @param guard Guard or decoder value provided by public callers.
+ * @param options Optional dialect and schema id configuration.
+ * @returns Export result with either a frozen JSON Schema document or issues.
  */
 export function toJsonSchema(guard, options) {
     if (isAsyncDecoderValue(guard)) {
@@ -35,13 +44,24 @@ export function toJsonSchema(guard, options) {
     return exportJsonSchema(readJsonSchemaGuardSchema(guard), options);
 }
 /**
- * @brief schema to json schema.
+ * @brief Export a raw TypeSea schema into a JSON Schema document.
+ * @details This internal-facing helper skips guard extraction but still routes
+ * through the same emitter and issue accumulator as the public guard API.
+ * @param schema Schema value that already passed TypeSea construction checks.
+ * @param options Optional dialect and schema id configuration.
+ * @returns Export result with a frozen JSON Schema document or diagnostics.
  */
 export function schemaToJsonSchema(schema, options) {
     return exportJsonSchema(readJsonSchemaSchema(schema), options);
 }
 /**
- * @brief export json schema.
+ * @brief Run the JSON Schema emitter and attach the dialect marker.
+ * @details The emitter writes structural failures into `issues` instead of
+ * throwing so callers can inspect every unsupported node discovered during the
+ * walk. Boolean schemas are wrapped to preserve a document-shaped top level.
+ * @param schema TypeSea schema selected for export.
+ * @param options User supplied export options, still unresolved.
+ * @returns Frozen JSON Schema document on success, or frozen export issues.
  */
 function exportJsonSchema(schema, options) {
     const config = readJsonSchemaOptions(options);

package/dist/json-schema/issue.d.ts

@@ -1,11 +1,14 @@
 /**
  * @file issue.ts
  * @brief JSON Schema export issue construction.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 import type { PathSegment } from "../issue/index.js";
 import type { JsonSchemaExportCode, JsonSchemaExportIssue } from "./types.js";
 /**
- * @brief push json schema issue.
+ * @brief Execute push json schema issue.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function pushJsonSchemaIssue(path: readonly PathSegment[], issues: JsonSchemaExportIssue[], code: JsonSchemaExportCode, message: string): void;
 //# sourceMappingURL=issue.d.ts.map

package/dist/json-schema/issue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../src/json-schema/issue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,MAAM,EAAE,qBAAqB,EAAE,EAC/B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,MAAM,GACd,IAAI,CAMN"}
+{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../src/json-schema/issue.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EACR,oBAAoB,EACpB,qBAAqB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,mBAAmB,CAC/B,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,MAAM,EAAE,qBAAqB,EAAE,EAC/B,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,MAAM,GAChB,IAAI,CAMN"}

package/dist/json-schema/issue.js

@@ -1,9 +1,12 @@
 /**
  * @file issue.ts
  * @brief JSON Schema export issue construction.
+ * @details JSON Schema helpers emit only representations that preserve TypeSea semantics or
+ * report a structured export issue.
  */
 /**
- * @brief push json schema issue.
+ * @brief Execute push json schema issue.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export function pushJsonSchemaIssue(path, issues, code, message) {
     issues.push({