schemair 0.2.0 → 0.4.0

package/README.md

@@ -1,11 +1,28 @@
 # SchemaIR for TypeScript
 
-The `schemair` package is the TypeScript implementation of SchemaIR. It exports
-model types, definition and payload validators, assignability checks, a type
-expression interpreter, and authoring builders. For the language-independent
-model and evaluation rules, start with the
-[project README](https://github.com/schemair/schemair#readme) and
-[protocol](https://github.com/schemair/schemair/tree/main/spec).
+[![npm version](https://img.shields.io/npm/v/schemair)](https://www.npmjs.com/package/schemair)
+[![CI](https://github.com/schemair/schemair/actions/workflows/ci.yml/badge.svg)](https://github.com/schemair/schemair/actions/workflows/ci.yml)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/schemair/schemair/blob/main/LICENSE)
+
+**Types as data.**
+
+SchemaIR is a language-independent protocol and intermediate representation
+for portable data contracts, operation definitions, and type calculations.
+
+The [`schemair` package](https://www.npmjs.com/package/schemair) is the
+TypeScript implementation. It represents contracts, operations, and type
+expressions as serializable data.
+
+For the protocol's theory, IR model, design philosophy, standard vocabulary,
+cross-language boundaries, and conformance rules, see the [SchemaIR project
+README](https://github.com/schemair/schemair#readme) and the [protocol
+specification](https://github.com/schemair/schemair/tree/main/spec). This page
+focuses on using SchemaIR from TypeScript and JavaScript.
+
+## About this implementation
+
+The package exports model types, definition and payload validators,
+assignability checks, a type expression interpreter, and authoring builders.
 
 The `schemair/authoring` entry point exposes two namespaces: `schema` contains
 builders for serializable `SchemaNode` contracts, while `expression` contains
@@ -25,11 +42,16 @@ context. Core validation and relation APIs remain provider-driven; import
 `standardPayloadContext` or `standardRelationContext` when the standard
 vocabulary policy is wanted.
 
+This binding implements the shared protocol and conformance rules. See the
+[implementation matrix](../IMPLEMENTATIONS.md) for coverage and status.
+
 ## Install
 
 Install the published package from npm:
 
 ```sh
+npm install schemair
+# or
 pnpm add schemair
 ```
 
@@ -37,7 +59,7 @@ To work on the implementation in this repository, run `pnpm install` in this
 directory. The published package provides ESM `.js` files for `import` and CJS
 `.cjs` files for `require`, with matching TypeScript declarations.
 
-## Define and validate a schema
+## Quick start
 
 Builders return ordinary serializable objects. You can also write the same
 `SchemaNode` data directly or read it from JSON. Validate untrusted definitions
@@ -62,6 +84,26 @@ if (result.status !== 'accepted') console.error(result.issues);
 needed `resolveRef`, `semanticProvider`, or `constraintProvider` in the payload
 context. Missing capabilities can produce `unknown`.
 
+For a catalog-backed schema, resolve refs once and reuse the snapshot for
+synchronous validation:
+
+```ts
+import { resolveSchemaReferencesAsync } from 'schemair/resolve';
+import { validatePayload } from 'schemair/payload';
+
+const closure = await resolveSchemaReferencesAsync(schema, { resolveRef });
+if (closure.status !== 'resolved') throw new Error(closure.issues[0]?.message);
+const result = validatePayload(value, schema, { refs: closure.graph.refs });
+```
+
+The `refs` context is a list of `{ refPath, schema }` entries. The path uses
+the same string-array shape as a `SchemaNode` ref; callers do not need to
+encode it into an object key.
+
+The validator does not perform catalog I/O when `refs` is supplied. Semantic
+and constraint providers are synchronous; prepare any external policy data
+before checking the payload.
+
 ## Infer a TypeScript payload type
 
 `Infer<Schema, Registry>` is available when the schema is authored in TypeScript and its
@@ -195,7 +237,7 @@ extension paths produce `unknown` and need an appropriate host provider.
 An annotation such as `std/string/secret/password` labels a string; it imposes no
 password-strength validation. `standardSchemaSatisfiability` reports
 `inhabited`, `emptySet`, or `unknown`; an undecidable combination is never
-silently treated as empty. See the [standard vocabulary specification](../spec/protocol/standard-vocabulary.md)
+silently treated as empty. See the [standard vocabulary specification](https://github.com/schemair/schemair/blob/main/spec/protocol/standard-vocabulary.md)
 for portable semantics and implementation boundaries.
 
 ## Define an operation
@@ -282,6 +324,25 @@ for (const issue of relation.issues) {
 }
 ```
 
+The `schemair/compatibility` entry point reports both substitution directions
+for a previous and next schema or operation. `previousToNext` asks whether
+values accepted by the previous declaration are accepted by the next one;
+`nextToPrevious` checks the reverse. Each side preserves the original relation
+result and diagnostics, while the report summarizes the pair as
+`compatible`, `breaking`, `unknown`, or `invalid`.
+
+```ts
+import { reportSchemaCompatibility } from 'schemair/compatibility';
+
+const report = reportSchemaCompatibility(previousSchema, nextSchema);
+if (report.status === 'breaking') {
+  console.log(report.previousToNext.relation.issues);
+}
+```
+
+This is a relation-based compatibility report. It does not choose a migration,
+versioning, or publication policy for the host.
+
 `validateStructuredOperationDefinition` and
 `validateStructuredOperationContainerDefinition` apply the same checks and
 reject binary payloads anywhere in the declaration. Their boolean companions,
@@ -307,7 +368,9 @@ if (relation.status === 'assignable') {
 
 The result is `assignable`, `incompatible`, `unknown`, or `rejected`. Supply
 resolver and provider callbacks in the relation context when comparison needs
-external information.
+external information. If references have already been loaded by a host, pass
+the immutable snapshot as `refs`; relation checking then remains synchronous and
+does not perform catalog I/O.
 
 ## Evaluate expressions
 
@@ -315,6 +378,31 @@ The type interpreter calculates authoring-time expressions. An evaluated
 result always has a `term`; it also has `schema` when that term can be
 materialized as a `SchemaNode`.
 
+For a synchronous, fully materialized run, load the reachable reference
+closure first and pass its immutable graph to the interpreter:
+
+```ts
+import { evaluateExpression } from 'schemair/type-interpreter';
+import { resolveSchemaReferencesAsync } from 'schemair/resolve';
+
+const closure = await resolveSchemaReferencesAsync(expression, { resolveRef });
+if (closure.status !== 'resolved') throw new Error(closure.issues[0]?.message);
+
+const result = evaluateExpression(expression, { refs: closure.graph.refs });
+```
+
+`resolveSchemaReferencesAsync` recursively loads every external reference reachable
+from the entry, including references inside resolved schemas. It preserves ref
+paths rather than inlining schemas. The `schemair/resolve` loader performs
+host-owned asynchronous I/O. `evaluateExpression` then uses the explicit `refs`
+snapshot, so the same evaluation request can run in a worker, server process,
+or WASM implementation. Term relations and solvers may additionally use
+explicit synchronous host policy callbacks.
+`selfRef` remains local to each schema root; recursive external refs stay as
+graph edges during loading and are bounded by the closure limits. The returned
+graph exposes those edges as `graph.cycles`. Resolve a closure once when refs
+come from a database or network, then reuse its snapshot across these calls.
+
 ```ts
 import { schema as s, expression as e } from 'schemair/authoring';
 import { evaluateExpression } from 'schemair/type-interpreter';
@@ -331,6 +419,11 @@ Unbound type variables remain in the evaluated term and appear in
 with structured issues. `checkTypeTermRelation` compares expression terms;
 `solveTypeVariables` infers invocation-local bindings for generic ports.
 
+Evaluation validates portable declarations before computing their results,
+including constraints on unresolved terms. It does not mutate input
+declarations and accepts frozen declarations. Type-variable upper bounds use
+the same preloaded reference environment as the binding being checked.
+
 ## Compare expression terms
 
 Unlike `checkSchemaRelation`, this API also compares terms that cannot become
@@ -379,44 +472,49 @@ if (solution.status === 'solved') {
 When a variable has no evidence, the solver lists it in `unresolved` instead
 of inventing a binding. Inspect `status` and `issues` before using a result.
 
-## Sync and async APIs
+## Asynchronous boundaries
 
-Use synchronous calls with in-memory resolvers and providers. For database or
-network-backed capabilities, use the asynchronous companions:
+Schema definition validation, expression evaluation, schema and operation
+relations, compatibility reports, type-variable solving, and payload validation are synchronous
+calculations. They accept in-memory data and synchronous callbacks. When refs
+are stored remotely, use `resolveSchemaReferencesAsync` or `resolveOperationClosureAsync`
+from `schemair/resolve` to load them first, then pass the resulting `refs`
+snapshot to the calculation. For an in-memory catalog, use the synchronous
+`resolveSchemaReferences` or `resolveOperationClosure` instead. Both modes
+share traversal, caching, limits, and diagnostics. Sync loaders reject promise
+results with an `incomplete` diagnostic; async loaders accept both immediate
+and promise results.
 
-| Synchronous | Asynchronous |
-| --- | --- |
-| `validatePayload` | `validatePayloadAsync` |
-| `checkSchemaRelation` | `checkSchemaRelationAsync` |
-| `evaluateExpression` | `evaluateExpressionAsync` |
-| `checkTypeTermRelation` | `checkTypeTermRelationAsync` |
-| `solveTypeVariables` | `solveTypeVariablesAsync` |
+```ts
+import { resolveSchemaReferences } from 'schemair/resolve';
+import { schema as s } from 'schemair/authoring';
 
-`validateSchemaNodeDefinition` is always synchronous. The async companions
-await caller-provided capabilities and use the same result categories as their
-sync counterparts.
+const loaded = resolveSchemaReferences(s.ref(['UserName']), {
+  resolveRef: (path) => path[0] === 'UserName' ? s.string() : undefined,
+});
+```
 
-For example, a reference catalog may live in a database:
+For example, load a reference catalog from a database before checking a value:
 
 ```ts
 import { schema as s } from 'schemair/authoring';
-import { validatePayloadAsync } from 'schemair/payload';
+import { validatePayload } from 'schemair/payload';
+import { resolveSchemaReferencesAsync } from 'schemair/resolve';
 
 const user = s.record([s.requiredField('name', s.string())]);
-const result = await validatePayloadAsync(
-  { name: 'Ada' },
-  s.ref(['catalog', 'user']),
-  {
-    resolveRef: async (path) =>
-      path.join('/') === 'catalog/user' ? user : undefined,
-  },
-);
+const ref = s.ref(['catalog', 'user']);
+const loaded = await resolveSchemaReferencesAsync(ref, {
+  resolveRef: async (path) =>
+    path.join('/') === 'catalog/user' ? user : undefined,
+});
+if (loaded.status !== 'resolved') throw new Error(loaded.issues[0]?.message);
+const result = validatePayload({ name: 'Ada' }, ref, { refs: loaded.graph.refs });
 console.log(result.status); // 'accepted'
 ```
 
-Async relation checks, expression evaluation, and variable solving accept
-async resolvers in their corresponding contexts. Payload semantic and
-constraint providers may also be async.
+Semantic and constraint providers are synchronous policies. Prepare external
+policy data before validation. Database uniqueness, permissions, and other
+business checks belong in the host workflow rather than the core validator.
 
 ## Standard Schema integration
 
@@ -431,12 +529,13 @@ const standard = schemaIRToStandardSchema(
   s.record([s.requiredField('name', s.string())]),
 );
 
-const result = await standard['~standard'].validate({ name: 'Ada' });
+const result = standard['~standard'].validate({ name: 'Ada' });
 ```
 
-The adapter always uses the asynchronous Standard Schema validator so the
-caller can provide asynchronous `resolveRef`, `semanticProvider`, and
-`constraintProvider` callbacks. Successful validation returns the original
+The adapter uses synchronous payload validation with preloaded `refs` and
+synchronous `resolveRef`, `semanticProvider`, and `constraintProvider`
+callbacks. Load external references before constructing the adapter.
+Successful validation returns the original
 input reference. Failed, unknown, unsupported, and unresolved validation
 outcomes are projected to Standard Schema `issues`; native SchemaIR payload
 diagnostics remain available through `schemair/payload`.
@@ -517,7 +616,9 @@ callbacks, and required diagnostics.
 | `schemair/definition` | Schema definition validation |
 | `schemair/payload` | Payload validation |
 | `schemair/relations` | SchemaNode assignability |
+| `schemair/compatibility` | Directional schema and operation compatibility reports |
 | `schemair/type-interpreter` | Expression evaluation and type-term relations |
+| `schemair/resolve` | Host-owned synchronous and asynchronous schema and operation reference loading |
 | `schemair/authoring` | `schema` builders, `expression` builders, and TypeScript-only `Infer<Schema>` |
 | `schemair/standard` | Standard semantic/constraint paths, registries, predicates, and relation helpers |
 | `schemair/standard-schema` | Standard Schema runtime adapter |

package/dist/authoring/index.d.cts

@@ -1,2 +1,2 @@
-import { a as InferOperationOutput, c as expression_d_exports, d as InferFailureReason, f as InferRef, h as StaticSchemaRegistryEntry, i as InferOperationInput, l as schema_d_exports, m as StaticSchemaRegistry, n as InferOperationEmits, o as InferOperationPayload, p as InferResult, r as InferOperationErrors, s as OperationRegistry, t as InferOperation, u as Infer } from "../index-CQynt7ft.cjs";
+import { a as InferOperationOutput, c as expression_d_exports, d as InferFailureReason, f as InferRef, h as StaticSchemaRegistryEntry, i as InferOperationInput, l as schema_d_exports, m as StaticSchemaRegistry, n as InferOperationEmits, o as InferOperationPayload, p as InferResult, r as InferOperationErrors, s as OperationRegistry, t as InferOperation, u as Infer } from "../index-CK7Is7vy.cjs";
 export { Infer, InferFailureReason, InferOperation, InferOperationEmits, InferOperationErrors, InferOperationInput, InferOperationOutput, InferOperationPayload, InferRef, InferResult, OperationRegistry, StaticSchemaRegistry, StaticSchemaRegistryEntry, expression_d_exports as expression, schema_d_exports as schema };

package/dist/authoring/index.d.ts

@@ -1,2 +1,2 @@
-import { a as InferOperationOutput, c as expression_d_exports, d as InferFailureReason, f as InferRef, h as StaticSchemaRegistryEntry, i as InferOperationInput, l as schema_d_exports, m as StaticSchemaRegistry, n as InferOperationEmits, o as InferOperationPayload, p as InferResult, r as InferOperationErrors, s as OperationRegistry, t as InferOperation, u as Infer } from "../index-bQy-C-1l.js";
+import { a as InferOperationOutput, c as expression_d_exports, d as InferFailureReason, f as InferRef, h as StaticSchemaRegistryEntry, i as InferOperationInput, l as schema_d_exports, m as StaticSchemaRegistry, n as InferOperationEmits, o as InferOperationPayload, p as InferResult, r as InferOperationErrors, s as OperationRegistry, t as InferOperation, u as Infer } from "../index-BTtdqi_M.js";
 export { Infer, InferFailureReason, InferOperation, InferOperationEmits, InferOperationErrors, InferOperationInput, InferOperationOutput, InferOperationPayload, InferRef, InferResult, OperationRegistry, StaticSchemaRegistry, StaticSchemaRegistryEntry, expression_d_exports as expression, schema_d_exports as schema };

package/dist/authoring/index.js

@@ -1,3 +1,3 @@
-import { n as schema_exports, t as expression_exports } from "../authoring-D3V0iyTe.js";
+import { n as schema_exports, t as expression_exports } from "../authoring-DyJNYs5o.js";
 
 export { expression_exports as expression, schema_exports as schema };

package/dist/{authoring-D3V0iyTe.js → authoring-DyJNYs5o.js}

@@ -1,4 +1,4 @@
-import { t as __exportAll } from "./chunk-BgLxgFZR.js";
+import { t as __exportAll } from "./chunk-bFfwrPtJ.js";
 
 //#region src/authoring/schema.ts
 var schema_exports = /* @__PURE__ */ __exportAll({

package/dist/compatibility/index.cjs

@@ -0,0 +1,43 @@
+const require_relations = require('../relations-NUVJkAG8.cjs');
+
+//#region src/compatibility/index.ts
+function status(relation) {
+	if (relation.status === "assignable") return "compatible";
+	if (relation.status === "incompatible") return "breaking";
+	if (relation.status === "unknown") return "unknown";
+	return "invalid";
+}
+function check(relation) {
+	return {
+		status: status(relation),
+		relation
+	};
+}
+function combine(left, right) {
+	if (left.status === "invalid" || right.status === "invalid") return "invalid";
+	if (left.status === "breaking" || right.status === "breaking") return "breaking";
+	if (left.status === "unknown" || right.status === "unknown") return "unknown";
+	return "compatible";
+}
+function reportSchemaCompatibility(previous, next, context = {}) {
+	const previousToNext = check(require_relations.checkSchemaRelation(previous, next, context));
+	const nextToPrevious = check(require_relations.checkSchemaRelation(next, previous, context));
+	return {
+		previousToNext,
+		nextToPrevious,
+		status: combine(previousToNext, nextToPrevious)
+	};
+}
+function reportOperationCompatibility(previous, next, context = {}) {
+	const previousToNext = check(require_relations.checkOperationRelation(previous, next, context));
+	const nextToPrevious = check(require_relations.checkOperationRelation(next, previous, context));
+	return {
+		previousToNext,
+		nextToPrevious,
+		status: combine(previousToNext, nextToPrevious)
+	};
+}
+
+//#endregion
+exports.reportOperationCompatibility = reportOperationCompatibility;
+exports.reportSchemaCompatibility = reportSchemaCompatibility;

package/dist/compatibility/index.d.cts

@@ -0,0 +1,2 @@
+import { a as reportSchemaCompatibility, i as reportOperationCompatibility, n as CompatibilityReport, r as CompatibilityStatus, t as CompatibilityCheck } from "../index-BfbClf6R.cjs";
+export { CompatibilityCheck, CompatibilityReport, CompatibilityStatus, reportOperationCompatibility, reportSchemaCompatibility };

package/dist/compatibility/index.d.ts

@@ -0,0 +1,2 @@
+import { a as reportSchemaCompatibility, i as reportOperationCompatibility, n as CompatibilityReport, r as CompatibilityStatus, t as CompatibilityCheck } from "../index-T6nFhvGQ.js";
+export { CompatibilityCheck, CompatibilityReport, CompatibilityStatus, reportOperationCompatibility, reportSchemaCompatibility };

package/dist/compatibility/index.js

@@ -0,0 +1,42 @@
+import { r as checkSchemaRelation, t as checkOperationRelation } from "../relations-QtnCRW9x.js";
+
+//#region src/compatibility/index.ts
+function status(relation) {
+	if (relation.status === "assignable") return "compatible";
+	if (relation.status === "incompatible") return "breaking";
+	if (relation.status === "unknown") return "unknown";
+	return "invalid";
+}
+function check(relation) {
+	return {
+		status: status(relation),
+		relation
+	};
+}
+function combine(left, right) {
+	if (left.status === "invalid" || right.status === "invalid") return "invalid";
+	if (left.status === "breaking" || right.status === "breaking") return "breaking";
+	if (left.status === "unknown" || right.status === "unknown") return "unknown";
+	return "compatible";
+}
+function reportSchemaCompatibility(previous, next, context = {}) {
+	const previousToNext = check(checkSchemaRelation(previous, next, context));
+	const nextToPrevious = check(checkSchemaRelation(next, previous, context));
+	return {
+		previousToNext,
+		nextToPrevious,
+		status: combine(previousToNext, nextToPrevious)
+	};
+}
+function reportOperationCompatibility(previous, next, context = {}) {
+	const previousToNext = check(checkOperationRelation(previous, next, context));
+	const nextToPrevious = check(checkOperationRelation(next, previous, context));
+	return {
+		previousToNext,
+		nextToPrevious,
+		status: combine(previousToNext, nextToPrevious)
+	};
+}
+
+//#endregion
+export { reportOperationCompatibility, reportSchemaCompatibility };

package/dist/definition/index.d.cts

@@ -1,3 +1,3 @@
-import { ct as SchemaNode, et as JsonValue } from "../index-DDMwVy2I.cjs";
-import { _ as validateStructuredOperationDefinition, a as validateSchemaTypeTermDefinition, b as SchemaNodeDefinitionValidationResult, c as OperationDefinitionPath, d as StructuredOperationDefinitionValidationResult, f as isStructuredOperationContainerDefinition, g as validateStructuredOperationContainerDefinition, h as validateOperationDefinition, i as validateSchemaTypeExprDefinition, l as OperationDefinitionValidationResult, m as validateOperationContainerDefinition, n as SchemaTypeExprDefinitionValidationResult, o as OperationContainerDefinitionValidationResult, p as isStructuredOperationDefinition, r as SchemaTypeTermDefinitionValidationResult, s as OperationDefinitionDiagnostic, t as SchemaTypeDefinitionDiagnostic, u as StructuredOperationContainerDefinitionValidationResult, v as SchemaNodeDefinitionDiagnostic, x as validateSchemaNodeDefinition, y as SchemaNodeDefinitionPath } from "../index-CIim1dG7.cjs";
+import { ct as SchemaNode, et as JsonValue } from "../index-i7Au-FQ6.cjs";
+import { _ as validateStructuredOperationDefinition, a as validateSchemaTypeTermDefinition, b as SchemaNodeDefinitionValidationResult, c as OperationDefinitionPath, d as StructuredOperationDefinitionValidationResult, f as isStructuredOperationContainerDefinition, g as validateStructuredOperationContainerDefinition, h as validateOperationDefinition, i as validateSchemaTypeExprDefinition, l as OperationDefinitionValidationResult, m as validateOperationContainerDefinition, n as SchemaTypeExprDefinitionValidationResult, o as OperationContainerDefinitionValidationResult, p as isStructuredOperationDefinition, r as SchemaTypeTermDefinitionValidationResult, s as OperationDefinitionDiagnostic, t as SchemaTypeDefinitionDiagnostic, u as StructuredOperationContainerDefinitionValidationResult, v as SchemaNodeDefinitionDiagnostic, x as validateSchemaNodeDefinition, y as SchemaNodeDefinitionPath } from "../index-DGHMUZ5m.cjs";
 export { JsonValue, OperationContainerDefinitionValidationResult, OperationDefinitionDiagnostic, OperationDefinitionPath, OperationDefinitionValidationResult, SchemaNode, SchemaNodeDefinitionDiagnostic, SchemaNodeDefinitionPath, SchemaNodeDefinitionValidationResult, SchemaTypeDefinitionDiagnostic, SchemaTypeExprDefinitionValidationResult, SchemaTypeTermDefinitionValidationResult, StructuredOperationContainerDefinitionValidationResult, StructuredOperationDefinitionValidationResult, isStructuredOperationContainerDefinition, isStructuredOperationDefinition, validateOperationContainerDefinition, validateOperationDefinition, validateSchemaNodeDefinition, validateSchemaTypeExprDefinition, validateSchemaTypeTermDefinition, validateStructuredOperationContainerDefinition, validateStructuredOperationDefinition };

package/dist/definition/index.d.ts

@@ -1,3 +1,3 @@
-import { ct as SchemaNode, et as JsonValue } from "../index-4aMF0cTE.js";
-import { _ as validateStructuredOperationDefinition, a as validateSchemaTypeTermDefinition, b as SchemaNodeDefinitionValidationResult, c as OperationDefinitionPath, d as StructuredOperationDefinitionValidationResult, f as isStructuredOperationContainerDefinition, g as validateStructuredOperationContainerDefinition, h as validateOperationDefinition, i as validateSchemaTypeExprDefinition, l as OperationDefinitionValidationResult, m as validateOperationContainerDefinition, n as SchemaTypeExprDefinitionValidationResult, o as OperationContainerDefinitionValidationResult, p as isStructuredOperationDefinition, r as SchemaTypeTermDefinitionValidationResult, s as OperationDefinitionDiagnostic, t as SchemaTypeDefinitionDiagnostic, u as StructuredOperationContainerDefinitionValidationResult, v as SchemaNodeDefinitionDiagnostic, x as validateSchemaNodeDefinition, y as SchemaNodeDefinitionPath } from "../index-DXWoNYFB.js";
+import { ct as SchemaNode, et as JsonValue } from "../index-1sDuqu05.js";
+import { _ as validateStructuredOperationDefinition, a as validateSchemaTypeTermDefinition, b as SchemaNodeDefinitionValidationResult, c as OperationDefinitionPath, d as StructuredOperationDefinitionValidationResult, f as isStructuredOperationContainerDefinition, g as validateStructuredOperationContainerDefinition, h as validateOperationDefinition, i as validateSchemaTypeExprDefinition, l as OperationDefinitionValidationResult, m as validateOperationContainerDefinition, n as SchemaTypeExprDefinitionValidationResult, o as OperationContainerDefinitionValidationResult, p as isStructuredOperationDefinition, r as SchemaTypeTermDefinitionValidationResult, s as OperationDefinitionDiagnostic, t as SchemaTypeDefinitionDiagnostic, u as StructuredOperationContainerDefinitionValidationResult, v as SchemaNodeDefinitionDiagnostic, x as validateSchemaNodeDefinition, y as SchemaNodeDefinitionPath } from "../index-CV8EZQy8.js";
 export { JsonValue, OperationContainerDefinitionValidationResult, OperationDefinitionDiagnostic, OperationDefinitionPath, OperationDefinitionValidationResult, SchemaNode, SchemaNodeDefinitionDiagnostic, SchemaNodeDefinitionPath, SchemaNodeDefinitionValidationResult, SchemaTypeDefinitionDiagnostic, SchemaTypeExprDefinitionValidationResult, SchemaTypeTermDefinitionValidationResult, StructuredOperationContainerDefinitionValidationResult, StructuredOperationDefinitionValidationResult, isStructuredOperationContainerDefinition, isStructuredOperationDefinition, validateOperationContainerDefinition, validateOperationDefinition, validateSchemaNodeDefinition, validateSchemaTypeExprDefinition, validateSchemaTypeTermDefinition, validateStructuredOperationContainerDefinition, validateStructuredOperationDefinition };

package/dist/definition/index.js

@@ -1,3 +1,3 @@
-import { c as validateOperationContainerDefinition, d as validateStructuredOperationDefinition, f as validateSchemaNodeDefinition, l as validateOperationDefinition, n as validateSchemaTypeTermDefinition, o as isStructuredOperationContainerDefinition, s as isStructuredOperationDefinition, t as validateSchemaTypeExprDefinition, u as validateStructuredOperationContainerDefinition } from "../definition-DmYnDmQO.js";
+import { c as validateOperationContainerDefinition, d as validateStructuredOperationDefinition, f as validateSchemaNodeDefinition, l as validateOperationDefinition, n as validateSchemaTypeTermDefinition, o as isStructuredOperationContainerDefinition, s as isStructuredOperationDefinition, t as validateSchemaTypeExprDefinition, u as validateStructuredOperationContainerDefinition } from "../definition-BH_LzXGc.js";
 
 export { isStructuredOperationContainerDefinition, isStructuredOperationDefinition, validateOperationContainerDefinition, validateOperationDefinition, validateSchemaNodeDefinition, validateSchemaTypeExprDefinition, validateSchemaTypeTermDefinition, validateStructuredOperationContainerDefinition, validateStructuredOperationDefinition };

package/dist/{index-DDMwVy2I.d.cts → index-1sDuqu05.d.ts}

@@ -82,6 +82,11 @@ interface SchemaSelfRefNode {
 }
 /** Closed serializable SchemaIR contract model. */
 type SchemaNode = SchemaPrimitiveNode | SchemaLiteralNode | SchemaRecordNode | SchemaArrayNode | SchemaTupleNode | SchemaLiteralUnionNode | SchemaNullableNode | SchemaTaggedUnionNode | SchemaRefNode | SchemaSelfRefNode;
+/** A host-provided schema bound for an external `refPath`. */
+interface SchemaRefEntry {
+  readonly refPath: readonly string[];
+  readonly schema: SchemaNode;
+}
 //#endregion
 //#region src/spec/operation.d.ts
 type OperationBinaryMetadata = {
@@ -365,4 +370,4 @@ declare const STANDARD_SEMANTIC_DEFINITIONS: ReadonlyArray<StandardSemanticDefin
 declare const STANDARD_SEMANTIC_RELATIONS: ReadonlyArray<StandardSemanticRelation>;
 declare const STANDARD_CONSTRAINT_DEFINITIONS: ReadonlyArray<StandardConstraintDefinition>;
 //#endregion
-export { StructuredOperationPayloadDefinition as $, SchemaTypeOpaqueHostExpr as A, SchemaTypeValueOfExpr as B, SchemaTypeIntersectExpr as C, SchemaTypeNeverExpr as D, SchemaTypeMergeRecordsExpr as E, SchemaTypeRequiredFieldsExpr as F, OperationChannelDefinition as G, SchemaVariantSelector as H, SchemaTypeTaggedUnionExpr as I, OperationErrorDefinition as J, OperationContainerDefinition as K, SchemaTypeTerm as L, SchemaTypePickFieldsExpr as M, SchemaTypeRecordExpr as N, SchemaTypeNullableExpr as O, SchemaTypeRefineExpr as P, StructuredOperationDefinition as Q, SchemaTypeTupleExpr as R, SchemaTypeFieldsOfExpr as S, SchemaTypeMaybeAbsentExpr as T, Operation as U, SchemaTypeVariableExpr as V, OperationBinaryMetadata as W, StructuredOperationChannelDefinition as X, OperationPayloadDefinition as Y, StructuredOperationContainerDefinition as Z, SchemaTypeElementOfExpr as _, SchemaStringNode as _t, StandardSemanticDefinition as a, SchemaConstraint as at, SchemaTypeExtractVariantsExpr as b, SchemaTupleNode as bt, STANDARD_CONSTRAINT_PATH_LIST as c, SchemaNode as ct, Expression as d, SchemaNumberNode as dt, JsonValue as et, ExpressionArgument as f, SchemaPrimitiveNode as ft, SchemaTypeElementAtExpr as g, SchemaSelfRefNode as gt, SchemaTypeArrayExpr as h, SchemaRefNode as ht, StandardConstraintDefinition as i, SchemaBooleanNode as it, SchemaTypePartialFieldsExpr as j, SchemaTypeOmitFieldsExpr as k, STANDARD_SEMANTIC_PATHS as l, SchemaNullNode as lt, SchemaTypeAbsentExpr as m, SchemaRecordNode as mt, STANDARD_SEMANTIC_DEFINITIONS as n, PrimitiveName as nt, StandardSemanticRelation as o, SchemaLiteralNode as ot, SchemaFieldSelector as p, SchemaRecordField as pt, OperationDefinition as q, STANDARD_SEMANTIC_RELATIONS as r, SchemaArrayNode as rt, STANDARD_CONSTRAINT_PATHS as s, SchemaLiteralUnionNode as st, STANDARD_CONSTRAINT_DEFINITIONS as t, LiteralValue as tt, STANDARD_SEMANTIC_PATH_LIST as u, SchemaNullableNode as ut, SchemaTypeExcludeVariantsExpr as v, SchemaTaggedUnionNode as vt, SchemaTypeKeyOfExpr as w, SchemaTypeFieldOfExpr as x, SchemaTypeExpr as y, SchemaTaggedUnionVariant as yt, SchemaTypeUnknownExpr as z };
+export { StructuredOperationPayloadDefinition as $, SchemaTypeOpaqueHostExpr as A, SchemaTypeValueOfExpr as B, SchemaTypeIntersectExpr as C, SchemaTypeNeverExpr as D, SchemaTypeMergeRecordsExpr as E, SchemaTypeRequiredFieldsExpr as F, OperationChannelDefinition as G, SchemaVariantSelector as H, SchemaTypeTaggedUnionExpr as I, OperationErrorDefinition as J, OperationContainerDefinition as K, SchemaTypeTerm as L, SchemaTypePickFieldsExpr as M, SchemaTypeRecordExpr as N, SchemaTypeNullableExpr as O, SchemaTypeRefineExpr as P, StructuredOperationDefinition as Q, SchemaTypeTupleExpr as R, SchemaTypeFieldsOfExpr as S, SchemaTypeMaybeAbsentExpr as T, Operation as U, SchemaTypeVariableExpr as V, OperationBinaryMetadata as W, StructuredOperationChannelDefinition as X, OperationPayloadDefinition as Y, StructuredOperationContainerDefinition as Z, SchemaTypeElementOfExpr as _, SchemaSelfRefNode as _t, StandardSemanticDefinition as a, SchemaConstraint as at, SchemaTypeExtractVariantsExpr as b, SchemaTaggedUnionVariant as bt, STANDARD_CONSTRAINT_PATH_LIST as c, SchemaNode as ct, Expression as d, SchemaNumberNode as dt, JsonValue as et, ExpressionArgument as f, SchemaPrimitiveNode as ft, SchemaTypeElementAtExpr as g, SchemaRefNode as gt, SchemaTypeArrayExpr as h, SchemaRefEntry as ht, StandardConstraintDefinition as i, SchemaBooleanNode as it, SchemaTypePartialFieldsExpr as j, SchemaTypeOmitFieldsExpr as k, STANDARD_SEMANTIC_PATHS as l, SchemaNullNode as lt, SchemaTypeAbsentExpr as m, SchemaRecordNode as mt, STANDARD_SEMANTIC_DEFINITIONS as n, PrimitiveName as nt, StandardSemanticRelation as o, SchemaLiteralNode as ot, SchemaFieldSelector as p, SchemaRecordField as pt, OperationDefinition as q, STANDARD_SEMANTIC_RELATIONS as r, SchemaArrayNode as rt, STANDARD_CONSTRAINT_PATHS as s, SchemaLiteralUnionNode as st, STANDARD_CONSTRAINT_DEFINITIONS as t, LiteralValue as tt, STANDARD_SEMANTIC_PATH_LIST as u, SchemaNullableNode as ut, SchemaTypeExcludeVariantsExpr as v, SchemaStringNode as vt, SchemaTypeKeyOfExpr as w, SchemaTypeFieldOfExpr as x, SchemaTupleNode as xt, SchemaTypeExpr as y, SchemaTaggedUnionNode as yt, SchemaTypeUnknownExpr as z };

package/dist/index-BFSMT_2d.d.ts

@@ -0,0 +1,53 @@
+import { ct as SchemaNode, gt as SchemaRefNode, ht as SchemaRefEntry, q as OperationDefinition } from "./index-1sDuqu05.js";
+
+//#region src/resolve/schema-closure.d.ts
+interface SchemaClosureDiagnostic {
+  readonly code: string;
+  readonly path: readonly (string | number)[];
+  readonly message: string;
+}
+type SchemaRefResolution = SchemaNode | {
+  readonly status: 'resolved';
+  readonly schema: SchemaNode;
+} | {
+  readonly status: 'unknown' | 'unsupported';
+  readonly message?: string;
+} | undefined;
+interface ResolvedSchemaGraph {
+  readonly refs: readonly SchemaRefEntry[];
+  /** External graph edges that point back to an active ref during loading. */
+  readonly cycles: readonly (readonly string[])[];
+}
+type SchemaClosureStatus = 'resolved' | 'incomplete' | 'rejected';
+interface SchemaClosureResult {
+  readonly status: SchemaClosureStatus;
+  readonly graph: ResolvedSchemaGraph;
+  readonly issues: readonly SchemaClosureDiagnostic[];
+}
+interface SchemaClosureContext {
+  readonly resolveRef?: (refPath: readonly string[], context: SchemaClosureResolutionContext) => SchemaRefResolution;
+  readonly refs?: readonly SchemaRefEntry[];
+  readonly maxDepth?: number;
+  readonly maxNodes?: number;
+  readonly maxSteps?: number;
+}
+/** Async loading accepts both synchronous and asynchronous host resolvers. */
+interface AsyncSchemaClosureContext extends Omit<SchemaClosureContext, 'resolveRef'> {
+  readonly resolveRef?: (refPath: readonly string[], context: SchemaClosureResolutionContext) => SchemaRefResolution | PromiseLike<SchemaRefResolution>;
+}
+/** Context supplied while the host resolves one ref during closure loading. */
+interface SchemaClosureResolutionContext {
+  readonly path: readonly (string | number)[];
+  readonly refPath: readonly string[];
+  readonly ref: SchemaRefNode;
+  readonly depth: number;
+}
+/** Load references using a synchronous host resolver. */
+declare function resolveSchemaReferences(entry: unknown, context?: SchemaClosureContext): SchemaClosureResult;
+/** Load references using a synchronous or asynchronous host resolver. */
+declare function resolveSchemaReferencesAsync(entry: unknown, context?: AsyncSchemaClosureContext): Promise<SchemaClosureResult>;
+/** Resolve all external schema refs reachable from an operation declaration. */
+declare function resolveOperationClosure(entry: OperationDefinition, context?: SchemaClosureContext): SchemaClosureResult;
+declare function resolveOperationClosureAsync(entry: OperationDefinition, context?: AsyncSchemaClosureContext): Promise<SchemaClosureResult>;
+//#endregion
+export { SchemaClosureResolutionContext as a, SchemaRefResolution as c, resolveSchemaReferences as d, resolveSchemaReferencesAsync as f, SchemaClosureDiagnostic as i, resolveOperationClosure as l, ResolvedSchemaGraph as n, SchemaClosureResult as o, SchemaClosureContext as r, SchemaClosureStatus as s, AsyncSchemaClosureContext as t, resolveOperationClosureAsync as u };

package/dist/{index-DM5DSLLL.d.ts → index-BGz7L_Fq.d.cts}

@@ -1,5 +1,5 @@
-import { L as SchemaTypeTerm, ct as SchemaNode, y as SchemaTypeExpr } from "./index-4aMF0cTE.js";
-import { a as AsyncRelationContext, o as RelationContext, p as RelationResult } from "./index-CBbd4hXJ.js";
+import { L as SchemaTypeTerm, ct as SchemaNode, ht as SchemaRefEntry, y as SchemaTypeExpr } from "./index-i7Au-FQ6.cjs";
+import { d as RelationResult, i as RelationContext } from "./index-ba_52Yu9.cjs";
 
 //#region src/type-interpreter/interpreter.d.ts
 type TypeInterpreterPath = readonly (string | number)[];
@@ -23,30 +23,14 @@ type TypeInterpreterResult = {
   readonly status: 'rejected';
   readonly issues: readonly TypeInterpreterDiagnostic[];
 };
-type TypeInterpreterRefResolution = SchemaNode | {
-  readonly status: 'resolved';
-  readonly schema: SchemaNode;
-} | {
-  readonly status: 'unknown' | 'unsupported';
-  readonly message?: string;
-} | undefined;
-type AsyncTypeInterpreterRefResolution = TypeInterpreterRefResolution | PromiseLike<TypeInterpreterRefResolution>;
 interface TypeInterpreterContext {
   readonly typeVars?: Readonly<Record<string, SchemaTypeTerm>>;
-  readonly resolveRef?: (refPath: readonly string[]) => TypeInterpreterRefResolution;
-  readonly maxDepth?: number;
-  readonly maxSteps?: number;
-}
-interface AsyncTypeInterpreterContext {
-  readonly typeVars?: Readonly<Record<string, SchemaTypeTerm>>;
-  readonly resolveRef?: (refPath: readonly string[]) => AsyncTypeInterpreterRefResolution;
+  readonly refs?: readonly SchemaRefEntry[];
   readonly maxDepth?: number;
   readonly maxSteps?: number;
 }
 declare function evaluateExpression(term: unknown, context?: TypeInterpreterContext): TypeInterpreterResult;
-declare function evaluateExpressionAsync(term: unknown, context?: AsyncTypeInterpreterContext): Promise<TypeInterpreterResult>;
 declare const evaluateSchemaTypeTerm: typeof evaluateExpression;
-declare const evaluateSchemaTypeTermAsync: typeof evaluateExpressionAsync;
 //#endregion
 //#region src/type-interpreter/term-relation.d.ts
 interface TypeTermRelationContext {
@@ -54,17 +38,11 @@ interface TypeTermRelationContext {
   readonly relation?: RelationContext;
   readonly hostTypeRelation?: (sourcePath: readonly string[], targetPath: readonly string[]) => HostTypeRelationDecision;
 }
-interface AsyncTypeTermRelationContext {
-  readonly interpreter?: AsyncTypeInterpreterContext;
-  readonly relation?: AsyncRelationContext;
-  readonly hostTypeRelation?: (sourcePath: readonly string[], targetPath: readonly string[]) => HostTypeRelationDecision | PromiseLike<HostTypeRelationDecision>;
-}
 type HostTypeRelationDecision = boolean | {
   readonly status: 'assignable' | 'incompatible' | 'unknown' | 'unsupported';
   readonly message?: string;
 };
 declare function checkTypeTermRelation(source: SchemaTypeTerm, target: SchemaTypeTerm, context?: TypeTermRelationContext): RelationResult;
-declare function checkTypeTermRelationAsync(source: SchemaTypeTerm, target: SchemaTypeTerm, context?: AsyncTypeTermRelationContext): Promise<RelationResult>;
 //#endregion
 //#region src/type-interpreter/type-variable-solver.d.ts
 interface TypeVariableConstraint {
@@ -90,10 +68,6 @@ interface TypeVariableSolverResult {
 interface TypeVariableSolverContext extends TypeTermRelationContext {
   readonly interpreter?: TypeInterpreterContext;
 }
-interface AsyncTypeVariableSolverContext extends AsyncTypeTermRelationContext {
-  readonly interpreter?: AsyncTypeInterpreterContext;
-}
 declare function solveTypeVariables(input: TypeVariableSolverInput, context?: TypeVariableSolverContext): TypeVariableSolverResult;
-declare function solveTypeVariablesAsync(input: TypeVariableSolverInput, context?: AsyncTypeVariableSolverContext): Promise<TypeVariableSolverResult>;
 //#endregion
-export { evaluateExpression as C, evaluateSchemaTypeTermAsync as E, TypeInterpreterStatus as S, evaluateSchemaTypeTerm as T, TypeInterpreterContext as _, TypeVariableSolverIssue as a, TypeInterpreterRefResolution as b, solveTypeVariablesAsync as c, TypeTermRelationContext as d, checkTypeTermRelation as f, EvaluatedTypeTerm as g, AsyncTypeInterpreterRefResolution as h, TypeVariableSolverInput as i, AsyncTypeTermRelationContext as l, AsyncTypeInterpreterContext as m, TypeVariableConstraint as n, TypeVariableSolverResult as o, checkTypeTermRelationAsync as p, TypeVariableSolverContext as r, solveTypeVariables as s, AsyncTypeVariableSolverContext as t, HostTypeRelationDecision as u, TypeInterpreterDiagnostic as v, evaluateExpressionAsync as w, TypeInterpreterResult as x, TypeInterpreterPath as y };
+export { evaluateSchemaTypeTerm as _, TypeVariableSolverResult as a, TypeTermRelationContext as c, TypeInterpreterContext as d, TypeInterpreterDiagnostic as f, evaluateExpression as g, TypeInterpreterStatus as h, TypeVariableSolverIssue as i, checkTypeTermRelation as l, TypeInterpreterResult as m, TypeVariableSolverContext as n, solveTypeVariables as o, TypeInterpreterPath as p, TypeVariableSolverInput as r, HostTypeRelationDecision as s, TypeVariableConstraint as t, EvaluatedTypeTerm as u };

package/dist/{index-bQy-C-1l.d.ts → index-BTtdqi_M.d.ts}

@@ -1,6 +1,6 @@
-import { G as OperationChannelDefinition, H as SchemaVariantSelector, L as SchemaTypeTerm, _t as SchemaStringNode, a as StandardSemanticDefinition, at as SchemaConstraint, bt as SchemaTupleNode, ct as SchemaNode, dt as SchemaNumberNode, ft as SchemaPrimitiveNode, gt as SchemaSelfRefNode, ht as SchemaRefNode, i as StandardConstraintDefinition, it as SchemaBooleanNode, lt as SchemaNullNode, mt as SchemaRecordNode, ot as SchemaLiteralNode, p as SchemaFieldSelector, pt as SchemaRecordField, q as OperationDefinition, rt as SchemaArrayNode, st as SchemaLiteralUnionNode, tt as LiteralValue, ut as SchemaNullableNode, vt as SchemaTaggedUnionNode, y as SchemaTypeExpr, yt as SchemaTaggedUnionVariant } from "./index-4aMF0cTE.js";
-import { f as SyncConstraintProvider, h as SyncSemanticProvider, m as SyncPayloadValidationContext } from "./index-BqfGAU1K.js";
-import { o as RelationContext } from "./index-CBbd4hXJ.js";
+import { G as OperationChannelDefinition, H as SchemaVariantSelector, L as SchemaTypeTerm, _t as SchemaSelfRefNode, a as StandardSemanticDefinition, at as SchemaConstraint, bt as SchemaTaggedUnionVariant, ct as SchemaNode, dt as SchemaNumberNode, ft as SchemaPrimitiveNode, gt as SchemaRefNode, i as StandardConstraintDefinition, it as SchemaBooleanNode, lt as SchemaNullNode, mt as SchemaRecordNode, ot as SchemaLiteralNode, p as SchemaFieldSelector, pt as SchemaRecordField, q as OperationDefinition, rt as SchemaArrayNode, st as SchemaLiteralUnionNode, tt as LiteralValue, ut as SchemaNullableNode, vt as SchemaStringNode, xt as SchemaTupleNode, y as SchemaTypeExpr, yt as SchemaTaggedUnionNode } from "./index-1sDuqu05.js";
+import { s as PayloadValidationContext, t as ConstraintProvider, u as SemanticProvider } from "./index-hrcM9oJe.js";
+import { i as RelationContext } from "./index-DxvfPmw6.js";
 
 //#region src/standard/runtime.d.ts
 type StandardSemanticResolution = 'standard' | 'extension' | 'unresolved';
@@ -71,13 +71,13 @@ declare function isStandardConstraintOwner(node: SchemaNode): node is StandardCo
 declare function buildStandardConstraintProfile(node: StandardConstraintOwner, options?: BuildStandardConstraintProfileOptions): StandardConstraintProfile;
 //#endregion
 //#region src/standard/payload.d.ts
-declare const standardSemanticProvider: SyncSemanticProvider;
+declare const standardSemanticProvider: SemanticProvider;
 declare function standardConstraintTarget(node: SchemaNode): string;
-declare const standardConstraintProvider: SyncConstraintProvider;
-declare const standardSemanticRegistry: Readonly<Record<string, SyncSemanticProvider>>;
-declare const standardConstraintRegistry: Readonly<Record<string, SyncConstraintProvider>>;
+declare const standardConstraintProvider: ConstraintProvider;
+declare const standardSemanticRegistry: Readonly<Record<string, SemanticProvider>>;
+declare const standardConstraintRegistry: Readonly<Record<string, ConstraintProvider>>;
 /** Opt in explicitly; core validation never silently installs vocabulary policy. */
-declare const standardPayloadContext: SyncPayloadValidationContext;
+declare const standardPayloadContext: PayloadValidationContext;
 //#endregion
 //#region src/standard/operations.d.ts
 type StandardSchemaOperationResult = {
@@ -101,7 +101,7 @@ interface StandardProviderContext {
 declare function createStandardRelationContext(options?: StandardProviderContext): RelationContext;
 declare const standardRelationContext: RelationContext;
 declare const standardVocabularyProvider: Readonly<{
-  payload: SyncPayloadValidationContext;
+  payload: PayloadValidationContext;
   relation: RelationContext;
   refine: typeof refineStandardSchema;
   intersect: typeof intersectStandardSchemas;