schemair 0.1.0 → 0.3.0

package/README.md

@@ -1,36 +1,76 @@
 # 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
+builders for serializable `SchemaTypeExpr` calculations. A schema node and an
+expression are both plain data and can be stored, exchanged, or evaluated by
+the interpreter.
+
+For statically authored contracts, `schemair/authoring` also exports the
+TypeScript-only `Infer<Schema>` utility. It projects a source-known schema into
+a payload carrier type; it does not alter the portable declaration or replace
+runtime payload validation.
+
+The optional `schemair/standard` entry point provides the protocol's `std`
+semantic and constraint vocabulary, including reusable paths, definitions,
+standard payload predicates, constraint reasoning, and an opt-in relation
+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
 
-Once the package is published:
+Install the published package from npm:
 
 ```sh
+npm install schemair
+# or
 pnpm add schemair
 ```
 
-Until then, run `pnpm install` in this directory to work with the repository
-copy. The package is configured to publish ESM `.js` files for `import` and
-CJS `.cjs` files for `require`, with matching TypeScript declarations.
+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
 before using them.
 
 ```ts
-import { record, requiredField, string } from 'schemair/authoring';
+import { schema as s } from 'schemair/authoring';
 import { validateSchemaNodeDefinition } from 'schemair/definition';
 import { validatePayload } from 'schemair/payload';
 
-const user = record([requiredField('name', string())]);
+const user = s.record([s.requiredField('name', s.string())]);
 const definition = validateSchemaNodeDefinition(user);
 if (!definition.ok) throw new Error(definition.issues[0]?.message);
 
@@ -44,16 +84,283 @@ 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
+literal structure remains available to the compiler. It supports primitive,
+literal, literal-union, nullable, array, tuple, record, and tagged-union
+nodes.
+
+```ts
+import { schema as s, type Infer } from 'schemair/authoring';
+
+const user = s.record([
+  s.requiredField('id', s.string()),
+  s.requiredField('age', s.number()),
+  s.optionalField('nickname', s.string()),
+]);
+
+type User = Infer<typeof user>;
+// { id: string; age: number; nickname?: string }
+```
+
+`Infer` is intentionally conservative. Named `ref` declarations can be resolved
+by passing a statically authored registry as the second parameter, including
+references nested inside another registered schema:
+
+```ts
+const registry = s.defineSchemaRegistry([
+  { refPath: ['users', 'User'] as const, name: 'User', schema: user },
+]);
+const order = s.record([s.requiredField('owner', s.ref(['users', 'User']))]);
+type Order = Infer<typeof order, typeof registry>;
+```
+
+Unresolved, dynamically shaped, ambiguous, or cyclic references project to
+`unknown`. `Infer` is intentionally conservative. Typed
+additional record fields, broad `SchemaNode` values, and unsupported or
+dynamically loaded declarations project to `unknown`. A structural `selfRef`
+can refer back to the root schema, so common tree-shaped records can be
+inferred recursively. Semantic paths and constraints remain their carrier
+types: an email is `string`, and an integer is `number`. Always use
+payload validation for data received at runtime.
+
+For statically known references, pair `InferRef` with a plain declaration
+registry:
+
+```ts
+import { schema as s, type InferRef } from 'schemair/authoring';
+
+const registry = s.defineSchemaRegistry([
+  { refPath: ['users', 'User'], name: 'User', schema: user },
+]);
+
+type UserFromRef = InferRef<typeof registry, ['users', 'User']>;
+```
+
+Missing or dynamically shaped paths project to `unknown`. The registry helper
+does not resolve references or replace runtime definition validation.
+
+`InferResult<Schema, Registry>` is the diagnostic form of the same projection.
+It keeps failures out of ordinary payload types and reports a small, stable
+reason such as `unresolved-ref`, `dynamic-ref-path`, or `unsupported-schema`:
+
+```ts
+import type { InferResult } from 'schemair/authoring';
+
+type CheckedUser = InferResult<typeof user>;
+// { ok: true; type: { id: string; age: number; nickname?: string } }
+type Missing = InferResult<typeof s.ref(['users', 'Missing'])>;
+// { ok: false; reason: 'unresolved-ref' }
+```
+
+This is a compile-time utility, not runtime validation. Use the definition
+validators when the declaration comes from JSON, a database, or an AI tool.
+
+## Validate expressions before evaluation
+
+Use `validateSchemaTypeExprDefinition(unknown)` to check an expression from
+JSON, a database, or an AI proposal. Use `validateSchemaTypeTermDefinition`
+when the declaration may be either a `SchemaNode` or a `SchemaTypeExpr`.
+
+```ts
+import { validateSchemaTypeExprDefinition } from 'schemair/definition';
+import { expression as e } from 'schemair/authoring';
+
+const result = validateSchemaTypeExprDefinition(e.fieldOf(e.typeVar('T'), 'name'));
+if (result.ok) console.log(result.expression);
+```
+
+Validation preserves the original declaration and reports diagnostics with
+paths. It checks nested terms, selectors, constraints, and JSON compatibility;
+it does not evaluate expressions, bind variables, resolve references, or call
+providers. Unbound variables and unresolved references are valid declarations.
+A structurally valid expression can still be rejected during evaluation (for
+example, selecting a field from a string). Validation has a depth limit of 64
+and a work limit of 10,000 visited JSON values; exceeding either rejects the
+check with an `expression.budget` diagnostic.
+
+## Use the standard vocabulary
+
+The optional `schemair/standard` entry provides 20 semantic definitions and
+13 constraint definitions, their path constants, registry metadata, and
+payload/relation providers. Install the providers explicitly when you want
+standard vocabulary decisions:
+
+```ts
+import { schema as s } from 'schemair/authoring';
+import { validatePayload } from 'schemair/payload';
+import {
+  STANDARD_SEMANTIC_PATHS, STANDARD_CONSTRAINT_PATHS,
+  standardPayloadContext,
+} from 'schemair/standard';
+
+const email = s.string({
+  semanticPath: [...STANDARD_SEMANTIC_PATHS.string.email],
+  constraints: [{ constraintPath: [...STANDARD_CONSTRAINT_PATHS.string.maxLength], args: 254 }],
+});
+const result = validatePayload('ada@example.com', email, standardPayloadContext);
+console.log(result.status); // accepted
+```
+
+Use `STANDARD_SEMANTIC_DEFINITIONS` and `STANDARD_CONSTRAINT_DEFINITIONS` to
+build vocabulary pickers, show validation versus annotation roles, or inspect
+constraint targets and argument domains. `standardRelationContext` supplies
+accepted-set reasoning to `checkSchemaRelation`; `createStandardRelationContext`
+lets the host select an additional semantic identity policy.
+
+The portable vocabulary specifies declarations and meaning. The TypeScript
+providers implement those meanings within a JavaScript host: numbers use
+finite binary64 values; string lengths count Unicode code points; patterns
+use the ECMAScript regex engine. Unsupported pattern syntax and unknown or
+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](https://github.com/schemair/schemair/blob/main/spec/protocol/standard-vocabulary.md)
+for portable semantics and implementation boundaries.
+
+## Define an operation
+
+An operation describes its input and output contracts as data. The host owns
+invocation and execution.
+
+```ts
+import { schema as s } from 'schemair/authoring';
+import type { OperationDefinition } from 'schemair/spec';
+
+const lookupUser: OperationDefinition = {
+  input: { kind: 'structured', schema: s.record([s.requiredField('id', s.string())]) },
+  output: { kind: 'structured', schema: s.record([s.requiredField('name', s.string())]) },
+};
+```
+
+For TypeScript consumers, operation inference projects structured payloads and
+lets the host choose the carrier for binary payloads. The carrier is a host
+policy and is not part of the portable operation declaration:
+
+```ts
+import type {
+  InferOperationInput, InferOperationOutput, InferOperationErrors,
+  InferOperationEmits,
+} from 'schemair/authoring';
+
+type Binary = { bytes: Uint8Array; mime?: string };
+type Input = InferOperationInput<typeof lookupUser>;
+type Output = InferOperationOutput<typeof lookupUser, never, Binary>;
+type Errors = InferOperationErrors<typeof lookupUser>;
+type Events = InferOperationEmits<typeof lookupUser, never, Binary>;
+```
+
+Absent input/output or payload data is represented as `undefined`; named error
+and event maps retain their keys. This is a TypeScript convenience layer and
+does not add functions, generic templates, or host carriers to the protocol.
+
+An operation definition is a concrete, transport-neutral contract. Its
+structured payloads contain `SchemaNode` data; functions, unresolved
+`SchemaTypeExpr` terms, and type-variable templates belong to the authoring
+layer and must be resolved before publishing the operation. This makes the
+same declaration usable by visual tools, workflow systems, and AI-assisted
+contract tools without requiring them to understand HTTP details.
+
+## Validate portable operation declarations
+
+Use `validateOperationDefinition` and `validateOperationContainerDefinition`
+from `schemair/definition` when loading declarations from JSON, a database, or
+an AI-assisted tool. Successful results return the original `operation` or
+`container`; failures return `issues` with `code`, `path`, and `message`.
+
+```ts
+import { validateOperationDefinition } from 'schemair/definition';
+
+const declaration: unknown = JSON.parse('{"emits":{"progress":{}}}');
+const result = validateOperationDefinition(declaration);
+if (result.ok) console.log(result.operation);
+else console.error(result.issues);
+```
+
+Operation payloads and error details contain concrete `SchemaNode` contracts.
+Type expressions, generic templates, functions, and execution bindings are
+outside this model. Each embedded schema is validated as its own root;
+reference resolution and vocabulary policy are supplied separately.
+
+## Compare operation contracts
+
+`checkOperationRelation(source, target)` explains whether `source` can replace
+`target` for a caller that follows the target contract. Its diagnostics retain
+the operation path and include `details.component` (`input`, `output`, `error`,
+or `emission`) plus the comparison direction when the issue comes from a
+nested schema relation. An input comparison is reported in the reversed
+direction because callers supply the target's input shape. An unproved
+semantic, constraint, reference, or binary metadata implication remains
+`unknown`.
+
+```ts
+import { checkOperationRelation } from 'schemair/relations';
+
+const relation = checkOperationRelation(sourceOperation, targetOperation);
+for (const issue of relation.issues) {
+  console.log(issue.path, issue.details?.component, issue.message);
+}
+```
+
+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,
+`isStructuredOperationDefinition` and
+`isStructuredOperationContainerDefinition`, narrow unknown input to the
+exported `StructuredOperation*` types. A successful check preserves the
+original declaration, including absent payloads and empty channels.
+
 ## Compare types
 
 `checkSchemaRelation(source, target)` asks whether values admitted by the
 source can be used where the target is expected.
 
 ```ts
-import { string } from 'schemair/authoring';
+import { schema as s } from 'schemair/authoring';
 import { checkSchemaRelation } from 'schemair/relations';
 
-const relation = checkSchemaRelation(string(), string());
+const relation = checkSchemaRelation(s.string(), s.string());
 if (relation.status === 'assignable') {
   // The source can be connected to the target.
 }
@@ -61,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
 
@@ -69,11 +378,36 @@ 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 { arrayOf, string } from 'schemair/authoring';
+import { schema as s, expression as e } from 'schemair/authoring';
 import { evaluateExpression } from 'schemair/type-interpreter';
 
-const result = evaluateExpression(arrayOf(string()));
+const result = evaluateExpression(e.arrayOf(s.string()));
 if (result.status === 'evaluated') {
   console.log(result.term);
   console.log(result.schema);
@@ -85,22 +419,193 @@ 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.
 
-## Sync and async APIs
+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.
 
-Use synchronous calls with in-memory resolvers and providers. For database or
-network-backed capabilities, use the asynchronous companions:
+## Compare expression terms
 
-| Synchronous | Asynchronous |
-| --- | --- |
-| `validatePayload` | `validatePayloadAsync` |
-| `checkSchemaRelation` | `checkSchemaRelationAsync` |
-| `evaluateExpression` | `evaluateExpressionAsync` |
-| `checkTypeTermRelation` | `checkTypeTermRelationAsync` |
-| `solveTypeVariables` | `solveTypeVariablesAsync` |
+Unlike `checkSchemaRelation`, this API also compares terms that cannot become
+`SchemaNode`, such as opaque host types. Equal host paths match directly;
+the host supplies any other native type relationship.
+
+```ts
+import { schema as s, expression as e } from 'schemair/authoring';
+import { checkTypeTermRelation } from 'schemair/type-interpreter';
+
+const mouseEvent = e.opaqueHostType(['dom', 'MouseEvent']);
+const event = e.opaqueHostType(['dom', 'Event']);
+const relation = checkTypeTermRelation(mouseEvent, event, {
+  hostTypeRelation: (source, target) =>
+    source.join('/') === 'dom/MouseEvent' && target.join('/') === 'dom/Event',
+});
+console.log(relation.status); // 'assignable'
+```
+
+## Solve type variables
+
+For a map-like operation, infer `T` from its input array and `U` from the
+mapper's output. The source-to-target constraints represent port connections.
+
+```ts
+import { schema as s, expression as e } from 'schemair/authoring';
+import { evaluateExpression, solveTypeVariables } from 'schemair/type-interpreter';
+
+const solution = solveTypeVariables({
+  variables: ['T', 'U'],
+  constraints: [
+    { source: s.array(s.number()), target: e.arrayOf(e.typeVar('T')) },
+    { source: s.string(), target: e.typeVar('U') },
+  ],
+});
+
+if (solution.status === 'solved') {
+  const output = evaluateExpression(e.arrayOf(e.typeVar('U')), {
+    typeVars: solution.bindings,
+  });
+  if (output.status === 'evaluated') console.log(output.schema);
+  // { kind: 'array', elementSchema: { kind: 'primitive', name: 'string' } }
+}
+```
+
+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.
+
+## Asynchronous boundaries
+
+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.
+
+```ts
+import { resolveSchemaReferences } from 'schemair/resolve';
+import { schema as s } from 'schemair/authoring';
+
+const loaded = resolveSchemaReferences(s.ref(['UserName']), {
+  resolveRef: (path) => path[0] === 'UserName' ? s.string() : undefined,
+});
+```
+
+For example, load a reference catalog from a database before checking a value:
+
+```ts
+import { schema as s } from 'schemair/authoring';
+import { validatePayload } from 'schemair/payload';
+import { resolveSchemaReferencesAsync } from 'schemair/resolve';
+
+const user = s.record([s.requiredField('name', s.string())]);
+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'
+```
+
+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
+
+The `schemair/standard-schema` subpath exposes a runtime-only Standard Schema
+adapter for dynamic `SchemaNode` data:
+
+```ts
+import { schemaIRToStandardSchema } from 'schemair/standard-schema';
+import { schema as s } from 'schemair/authoring';
+
+const standard = schemaIRToStandardSchema(
+  s.record([s.requiredField('name', s.string())]),
+);
+
+const result = standard['~standard'].validate({ name: 'Ada' });
+```
+
+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`.
+
+Because the adapter receives runtime schema data, it intentionally does not
+claim a static `~standard.types` input/output type. It is a runtime adapter,
+not a typed authoring inference surface.
+
+## JSON Schema and OpenAPI integration
+
+The `schemair/json-schema` subpath projects a `SchemaNode` to JSON Schema
+Draft 2020-12 by default. Draft-07 is also supported with its legacy tuple and
+exclusive-bound keywords. OpenAPI 3.0 is available as a separate Schema Object
+projection through `schemaNodeToOpenApiSchema` or the Standard JSON Schema V1
+target. It is intentionally described as a projection rather than a full JSON
+Schema dialect because OpenAPI 3.0 cannot represent every SchemaIR construct.
+
+The exporter uses native keywords whenever the meaning is equivalent and
+returns projection diagnostics for anything that cannot be represented exactly:
+
+```ts
+import { schemaNodeToJsonSchema } from 'schemair/json-schema';
+
+const result = schemaNodeToJsonSchema({
+  kind: 'primitive',
+  name: 'string',
+  semanticPath: ['ext', 'money'],
+});
+
+// result.schema contains { type: 'string', 'x-schemair': { semanticPath: [...] } }
+// result.fidelity is 'exact', 'lossy', or 'unsupported'.
+```
+
+Select a JSON Schema dialect explicitly when needed:
+
+```ts
+const draft07 = schemaNodeToJsonSchema(tupleNode, { target: 'draft-07' });
+// Draft-07 tuples use items: [...] and additionalItems: false.
+```
+
+OpenAPI 3.0 uses `nullable: true` for nullable schemas and preserves tuple
+positions, literals, semantic identity, and other non-native details under
+`x-schemair`. Standalone `null` schemas and unresolved references are reported
+as `unsupported`; lossy projections are reported in `diagnostics` and are not
+silently treated as exact.
+
+Unmapped semantic paths, constraints, and references are retained under the
+`x-schemair` object. A caller may supply `semanticMapper`, `constraintMapper`,
+and `refStrategy` options for host-owned vocabularies and reference catalogs.
+The exporter never silently drops SchemaIR metadata.
+
+The same subpath also implements [Standard JSON Schema V1](https://standardschema.dev/json-schema):
+
+```ts
+import { schemaIRToStandardJsonSchema } from 'schemair/json-schema';
+
+const standard = schemaIRToStandardJsonSchema(user);
+const jsonSchema = standard['~standard'].jsonSchema.input({
+  target: 'draft-2020-12',
+});
+```
+
+`input()` and `output()` are identical because SchemaIR declarations do not
+perform value transformations. Unsupported targets or projections throw; a
+lossy projection is returned when its original metadata is preserved in
+`x-schemair`.
 
-`validateSchemaNodeDefinition` is always synchronous. The async companions
-await caller-provided capabilities and use the same result categories as their
-sync counterparts.
+See the [JSON Schema compatibility matrix](./docs/json-schema-compatibility.md)
+for the target-by-target fidelity rules, extension fields, capability
+callbacks, and required diagnostics.
 
 ## Package entry points
 
@@ -111,8 +616,13 @@ sync counterparts.
 | `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/authoring` | Data-construction helpers |
+| `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 |
+| `schemair/json-schema` | JSON Schema Draft-2020-12/Draft-07 and OpenAPI 3.0 projections |
 
 `src/internal/` is not exported. The package provides no ref registry,
 semantic vocabulary implementation, persistence layer, graph scheduler, or