schemair 0.1.0 → 0.2.0

package/README.md

@@ -7,17 +7,35 @@ 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).
 
+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.
+
 ## Install
 
-Once the package is published:
+Install the published package from npm:
 
 ```sh
 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
 
@@ -26,11 +44,11 @@ Builders return ordinary serializable objects. You can also write the same
 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 +62,244 @@ if (result.status !== 'accepted') console.error(result.issues);
 needed `resolveRef`, `semanticProvider`, or `constraintProvider` in the payload
 context. Missing capabilities can produce `unknown`.
 
+## 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](../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);
+}
+```
+
+`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.
 }
@@ -70,10 +316,10 @@ result always has a `term`; it also has `schema` when that term can be
 materialized as a `SchemaNode`.
 
 ```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,6 +331,54 @@ 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.
 
+## Compare expression terms
+
+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.
+
 ## Sync and async APIs
 
 Use synchronous calls with in-memory resolvers and providers. For database or
@@ -102,6 +396,118 @@ network-backed capabilities, use the asynchronous companions:
 await caller-provided capabilities and use the same result categories as their
 sync counterparts.
 
+For example, a reference catalog may live in a database:
+
+```ts
+import { schema as s } from 'schemair/authoring';
+import { validatePayloadAsync } from 'schemair/payload';
+
+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,
+  },
+);
+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.
+
+## 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 = await 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
+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`.
+
+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
 
 | Import path | Contents |
@@ -112,7 +518,10 @@ sync counterparts.
 | `schemair/payload` | Payload validation |
 | `schemair/relations` | SchemaNode assignability |
 | `schemair/type-interpreter` | Expression evaluation and type-term relations |
-| `schemair/authoring` | Data-construction helpers |
+| `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