@ultimat3/schema 1.0.0

package/src/json-schema.js

@@ -0,0 +1,108 @@
+// Single responsibility: SchemaNode -> JSON Schema. Load-bearing: OpenAPI request/response
+// bodies and MCP tool `inputSchema` are both this function's output, so an agent's view of an
+// action and an HTTP client's view can never drift.
+import { requiredKeys } from './node';
+import { introspect } from './provider';
+const DIALECTS = Object.freeze({
+    '2020-12': 'https://json-schema.org/draft/2020-12/schema',
+    'draft-07': 'http://json-schema.org/draft-07/schema#',
+});
+const FORMAT_MAP = Object.freeze({
+    uuid: 'uuid',
+    email: 'email',
+    uri: 'uri',
+    'date-time': 'date-time',
+    slug: 'slug',
+    timezone: 'iana-time-zone',
+    locale: 'bcp47-locale',
+    cursor: 'ultimate-cursor',
+});
+function stringNode(node) {
+    return {
+        type: 'string',
+        ...(node.format === undefined ? {} : { format: FORMAT_MAP[node.format] ?? node.format }),
+        ...(node.minLength === undefined ? {} : { minLength: node.minLength }),
+        ...(node.maxLength === undefined ? {} : { maxLength: node.maxLength }),
+        ...(node.pattern === undefined ? {} : { pattern: node.pattern }),
+    };
+}
+function convert(node) {
+    const annotate = (schema) => ({
+        ...schema,
+        ...(node.description === undefined ? {} : { description: node.description }),
+        ...(node.hasDefault === true ? { default: node.default } : {}),
+    });
+    switch (node.kind) {
+        case 'string':
+            return annotate(stringNode(node));
+        case 'number':
+            return annotate({
+                type: node.integer === true ? 'integer' : 'number',
+                ...(node.minimum === undefined ? {} : { minimum: node.minimum }),
+                ...(node.maximum === undefined ? {} : { maximum: node.maximum }),
+            });
+        case 'boolean':
+            return annotate({ type: 'boolean' });
+        case 'date':
+            return annotate({ type: 'string', format: 'date-time' });
+        case 'enum':
+            return annotate({ type: 'string', enum: node.values ?? [] });
+        case 'literal':
+            return annotate({ const: node.literal ?? null });
+        case 'array':
+            return annotate({
+                type: 'array',
+                items: node.items === undefined ? {} : convert(node.items),
+            });
+        case 'union':
+            return annotate({ anyOf: (node.anyOf ?? []).map(convert) });
+        case 'record':
+            return annotate({
+                type: 'object',
+                additionalProperties: node.valueNode === undefined ? true : convert(node.valueNode),
+            });
+        case 'money':
+            return annotate({
+                type: 'object',
+                properties: {
+                    minor: { type: 'integer', description: 'amount in minor units, never a float' },
+                    currency: { type: 'string', pattern: '^[A-Z]{3}$' },
+                },
+                required: ['minor', 'currency'],
+                additionalProperties: false,
+            });
+        case 'object': {
+            const properties = {};
+            for (const [key, child] of Object.entries(node.properties ?? {})) {
+                properties[key] = convert(child);
+            }
+            return annotate({
+                type: 'object',
+                properties,
+                required: requiredKeys(node),
+                additionalProperties: false,
+            });
+        }
+        default:
+            return annotate({});
+    }
+}
+/** Convert any schema the active provider can introspect. */
+export function toJsonSchema(schema, options) {
+    const converted = convert(introspect(schema));
+    const dialect = options?.dialect ?? '2020-12';
+    return {
+        ...(options?.includeDialect === false ? {} : { $schema: DIALECTS[dialect] }),
+        ...(options?.title === undefined ? {} : { title: options.title }),
+        ...converted,
+    };
+}
+/** The exact shape an MCP `tools/list` entry needs: draft-07, no `$schema`. */
+export function toMcpInputSchema(schema) {
+    return toJsonSchema(schema, { dialect: 'draft-07', includeDialect: false });
+}
+/** Convert an already-introspected node — used by generators that walk the IR themselves. */
+export function nodeToJsonSchema(node) {
+    return convert(node);
+}
+//# sourceMappingURL=json-schema.js.map

package/src/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","sourceRoot":"","sources":["json-schema.ts"],"names":[],"mappings":"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"}

package/src/json-schema.ts

@@ -0,0 +1,149 @@
+// Single responsibility: SchemaNode -> JSON Schema. Load-bearing: OpenAPI request/response
+// bodies and MCP tool `inputSchema` are both this function's output, so an agent's view of an
+// action and an HTTP client's view can never drift.
+
+import { requiredKeys, type SchemaNode } from './node';
+import { introspect } from './provider';
+
+export type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+
+export interface JsonSchema {
+  readonly $schema?: string;
+  readonly type?: JsonSchemaType;
+  readonly format?: string;
+  readonly description?: string;
+  readonly default?: unknown;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly enum?: readonly (string | number)[];
+  readonly const?: string | number | boolean | null;
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly items?: JsonSchema;
+  readonly anyOf?: readonly JsonSchema[];
+  readonly title?: string;
+}
+
+export type JsonSchemaDialect = '2020-12' | 'draft-07';
+
+const DIALECTS: Readonly<Record<JsonSchemaDialect, string>> = Object.freeze({
+  '2020-12': 'https://json-schema.org/draft/2020-12/schema',
+  'draft-07': 'http://json-schema.org/draft-07/schema#',
+});
+
+export interface ToJsonSchemaOptions {
+  /** MCP clients are happiest with `draft-07`; OpenAPI 3.1 wants `2020-12` (the default). */
+  readonly dialect?: JsonSchemaDialect | undefined;
+  /** Emit `$schema` at the root. Off for OpenAPI component schemas. */
+  readonly includeDialect?: boolean | undefined;
+  readonly title?: string | undefined;
+}
+
+const FORMAT_MAP: Readonly<Record<string, string>> = Object.freeze({
+  uuid: 'uuid',
+  email: 'email',
+  uri: 'uri',
+  'date-time': 'date-time',
+  slug: 'slug',
+  timezone: 'iana-time-zone',
+  locale: 'bcp47-locale',
+  cursor: 'ultimate-cursor',
+});
+
+function stringNode(node: SchemaNode): JsonSchema {
+  return {
+    type: 'string',
+    ...(node.format === undefined ? {} : { format: FORMAT_MAP[node.format] ?? node.format }),
+    ...(node.minLength === undefined ? {} : { minLength: node.minLength }),
+    ...(node.maxLength === undefined ? {} : { maxLength: node.maxLength }),
+    ...(node.pattern === undefined ? {} : { pattern: node.pattern }),
+  };
+}
+
+function convert(node: SchemaNode): JsonSchema {
+  const annotate = (schema: JsonSchema): JsonSchema => ({
+    ...schema,
+    ...(node.description === undefined ? {} : { description: node.description }),
+    ...(node.hasDefault === true ? { default: node.default } : {}),
+  });
+
+  switch (node.kind) {
+    case 'string':
+      return annotate(stringNode(node));
+    case 'number':
+      return annotate({
+        type: node.integer === true ? 'integer' : 'number',
+        ...(node.minimum === undefined ? {} : { minimum: node.minimum }),
+        ...(node.maximum === undefined ? {} : { maximum: node.maximum }),
+      });
+    case 'boolean':
+      return annotate({ type: 'boolean' });
+    case 'date':
+      return annotate({ type: 'string', format: 'date-time' });
+    case 'enum':
+      return annotate({ type: 'string', enum: node.values ?? [] });
+    case 'literal':
+      return annotate({ const: node.literal ?? null });
+    case 'array':
+      return annotate({
+        type: 'array',
+        items: node.items === undefined ? {} : convert(node.items),
+      });
+    case 'union':
+      return annotate({ anyOf: (node.anyOf ?? []).map(convert) });
+    case 'record':
+      return annotate({
+        type: 'object',
+        additionalProperties: node.valueNode === undefined ? true : convert(node.valueNode),
+      });
+    case 'money':
+      return annotate({
+        type: 'object',
+        properties: {
+          minor: { type: 'integer', description: 'amount in minor units, never a float' },
+          currency: { type: 'string', pattern: '^[A-Z]{3}$' },
+        },
+        required: ['minor', 'currency'],
+        additionalProperties: false,
+      });
+    case 'object': {
+      const properties: Record<string, JsonSchema> = {};
+      for (const [key, child] of Object.entries(node.properties ?? {})) {
+        properties[key] = convert(child);
+      }
+      return annotate({
+        type: 'object',
+        properties,
+        required: requiredKeys(node),
+        additionalProperties: false,
+      });
+    }
+    default:
+      return annotate({});
+  }
+}
+
+/** Convert any schema the active provider can introspect. */
+export function toJsonSchema(schema: unknown, options?: ToJsonSchemaOptions): JsonSchema {
+  const converted = convert(introspect(schema));
+  const dialect = options?.dialect ?? '2020-12';
+  return {
+    ...(options?.includeDialect === false ? {} : { $schema: DIALECTS[dialect] }),
+    ...(options?.title === undefined ? {} : { title: options.title }),
+    ...converted,
+  };
+}
+
+/** The exact shape an MCP `tools/list` entry needs: draft-07, no `$schema`. */
+export function toMcpInputSchema(schema: unknown): JsonSchema {
+  return toJsonSchema(schema, { dialect: 'draft-07', includeDialect: false });
+}
+
+/** Convert an already-introspected node — used by generators that walk the IR themselves. */
+export function nodeToJsonSchema(node: SchemaNode): JsonSchema {
+  return convert(node);
+}

package/src/node.d.ts

@@ -0,0 +1,32 @@
+export type SchemaKind = 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array' | 'enum' | 'literal' | 'union' | 'record' | 'money' | 'unknown';
+/** JSON Schema `format`, plus the framework's own semantic formats. */
+export type SchemaFormat = 'uuid' | 'email' | 'uri' | 'date-time' | 'slug' | 'timezone' | 'locale' | 'cursor';
+export interface SchemaNode {
+    readonly kind: SchemaKind;
+    readonly optional?: boolean | undefined;
+    /** Separate from `optional`: JSON Schema and the DB both distinguish null from absent. */
+    readonly nullable?: boolean | undefined;
+    readonly hasDefault?: boolean | undefined;
+    readonly default?: unknown;
+    readonly description?: string | undefined;
+    readonly format?: SchemaFormat | undefined;
+    readonly minLength?: number | undefined;
+    readonly maxLength?: number | undefined;
+    /** Source string of the RegExp, so the node stays JSON-serialisable. */
+    readonly pattern?: string | undefined;
+    readonly minimum?: number | undefined;
+    readonly maximum?: number | undefined;
+    readonly integer?: boolean | undefined;
+    readonly properties?: Readonly<Record<string, SchemaNode>> | undefined;
+    readonly items?: SchemaNode | undefined;
+    readonly values?: readonly (string | number)[] | undefined;
+    readonly literal?: string | number | boolean | null | undefined;
+    readonly anyOf?: readonly SchemaNode[] | undefined;
+    readonly valueNode?: SchemaNode | undefined;
+}
+export declare function isSchemaNode(value: unknown): value is SchemaNode;
+/** Duck-typed: any object carrying a `node` is introspectable, whatever built it. */
+export declare function nodeOf(value: unknown): SchemaNode | undefined;
+/** Keys an object node requires — everything not optional and without a default. */
+export declare function requiredKeys(node: SchemaNode): readonly string[];
+//# sourceMappingURL=node.d.ts.map

package/src/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["node.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,MAAM,GACN,QAAQ,GACR,OAAO,GACP,MAAM,GACN,SAAS,GACT,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,CAAC;AAEd,uEAAuE;AACvE,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,OAAO,GACP,KAAK,GACL,WAAW,GACX,MAAM,GACN,UAAU,GACV,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAAG,SAAS,CAAC;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC7C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAMhE;AAED,qFAAqF;AACrF,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAI7D;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,CAKhE"}

package/src/node.js

@@ -0,0 +1,24 @@
+// Single responsibility: the introspectable schema IR. Flat on purpose — OpenAPI generation,
+// MCP tool schemas, HTTP query coercion and the admin form generator all read this one shape,
+// so it must stay trivially walkable.
+export function isSchemaNode(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.kind === 'string');
+}
+/** Duck-typed: any object carrying a `node` is introspectable, whatever built it. */
+export function nodeOf(value) {
+    if (typeof value !== 'object' || value === null || !('node' in value))
+        return undefined;
+    const node = value.node;
+    return isSchemaNode(node) ? node : undefined;
+}
+/** Keys an object node requires — everything not optional and without a default. */
+export function requiredKeys(node) {
+    if (node.properties === undefined)
+        return [];
+    return Object.entries(node.properties)
+        .filter(([, child]) => child.optional !== true && child.hasDefault !== true)
+        .map(([key]) => key);
+}
+//# sourceMappingURL=node.js.map

package/src/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["node.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,8FAA8F;AAC9F,sCAAsC;AAmDtC,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CACvD,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxF,MAAM,IAAI,GAAI,KAA2B,CAAC,IAAI,CAAC;IAC/C,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,YAAY,CAAC,IAAgB;IAC3C,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAC7C,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;SACnC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;SAC3E,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/src/node.ts

@@ -0,0 +1,75 @@
+// Single responsibility: the introspectable schema IR. Flat on purpose — OpenAPI generation,
+// MCP tool schemas, HTTP query coercion and the admin form generator all read this one shape,
+// so it must stay trivially walkable.
+
+export type SchemaKind =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'object'
+  | 'array'
+  | 'enum'
+  | 'literal'
+  | 'union'
+  | 'record'
+  | 'money'
+  | 'unknown';
+
+/** JSON Schema `format`, plus the framework's own semantic formats. */
+export type SchemaFormat =
+  | 'uuid'
+  | 'email'
+  | 'uri'
+  | 'date-time'
+  | 'slug'
+  | 'timezone'
+  | 'locale'
+  | 'cursor';
+
+export interface SchemaNode {
+  readonly kind: SchemaKind;
+  readonly optional?: boolean | undefined;
+  /** Separate from `optional`: JSON Schema and the DB both distinguish null from absent. */
+  readonly nullable?: boolean | undefined;
+  readonly hasDefault?: boolean | undefined;
+  readonly default?: unknown;
+  readonly description?: string | undefined;
+  readonly format?: SchemaFormat | undefined;
+  readonly minLength?: number | undefined;
+  readonly maxLength?: number | undefined;
+  /** Source string of the RegExp, so the node stays JSON-serialisable. */
+  readonly pattern?: string | undefined;
+  readonly minimum?: number | undefined;
+  readonly maximum?: number | undefined;
+  readonly integer?: boolean | undefined;
+  readonly properties?: Readonly<Record<string, SchemaNode>> | undefined;
+  readonly items?: SchemaNode | undefined;
+  readonly values?: readonly (string | number)[] | undefined;
+  readonly literal?: string | number | boolean | null | undefined;
+  readonly anyOf?: readonly SchemaNode[] | undefined;
+  readonly valueNode?: SchemaNode | undefined;
+}
+
+export function isSchemaNode(value: unknown): value is SchemaNode {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { kind?: unknown }).kind === 'string'
+  );
+}
+
+/** Duck-typed: any object carrying a `node` is introspectable, whatever built it. */
+export function nodeOf(value: unknown): SchemaNode | undefined {
+  if (typeof value !== 'object' || value === null || !('node' in value)) return undefined;
+  const node = (value as { node: unknown }).node;
+  return isSchemaNode(node) ? node : undefined;
+}
+
+/** Keys an object node requires — everything not optional and without a default. */
+export function requiredKeys(node: SchemaNode): readonly string[] {
+  if (node.properties === undefined) return [];
+  return Object.entries(node.properties)
+    .filter(([, child]) => child.optional !== true && child.hasDefault !== true)
+    .map(([key]) => key);
+}

package/src/provider.d.ts

@@ -0,0 +1,32 @@
+import { type SchemaNode } from './node';
+import { type TNamespace } from './validators';
+export interface SchemaProvider {
+    /** Matches `~standard.vendor`, e.g. `ultimate`, `arktype`, `zod`. */
+    readonly vendor: string;
+    readonly t: TNamespace;
+    /**
+     * Return the IR for one of this provider's schemas. Required for OpenAPI and MCP tool
+     * schemas; omit it only if the provider also supplies `toJsonSchema`.
+     */
+    introspect?(schema: unknown): SchemaNode | undefined;
+}
+export declare const builtinProvider: SchemaProvider;
+/**
+ * Swap the library behind `t`.
+ *
+ * ```ts
+ * import { z } from 'zod';
+ * configureSchemaProvider({ vendor: 'zod', t: zodNamespace, introspect: zodToNode });
+ * ```
+ */
+export declare function configureSchemaProvider(provider: SchemaProvider): void;
+export declare function schemaProvider(): SchemaProvider;
+export declare function resetSchemaProvider(): void;
+/**
+ * The IR for any schema, whoever built it. Throws `X_SCHEMA_UNSUPPORTED` rather than silently
+ * emitting an empty OpenAPI body.
+ */
+export declare function introspect(schema: unknown): SchemaNode;
+/** Best-effort variant for callers that can degrade (HTTP query coercion). */
+export declare function tryIntrospect(schema: unknown): SchemaNode | undefined;
+//# sourceMappingURL=provider.d.ts.map

package/src/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["provider.ts"],"names":[],"mappings":"AAKA,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;CACtD;AAED,eAAO,MAAM,eAAe,EAAE,cAI5B,CAAC;AAIH;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAEtE;AAED,wBAAgB,cAAc,IAAI,cAAc,CAE/C;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,CAUtD;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAErE"}

package/src/provider.js

@@ -0,0 +1,49 @@
+// Single responsibility: the swap point. One provider is active per process; everything that
+// consumes schemas (OpenAPI, MCP, coercion, the admin form generator) goes through `introspect`
+// so a third-party library can be plugged in without touching the rest of the framework.
+import { SchemaUnsupportedError } from './errors';
+import { nodeOf } from './node';
+import { builtinT } from './validators';
+export const builtinProvider = Object.freeze({
+    vendor: 'ultimate',
+    t: builtinT,
+    introspect: nodeOf,
+});
+let active = builtinProvider;
+/**
+ * Swap the library behind `t`.
+ *
+ * ```ts
+ * import { z } from 'zod';
+ * configureSchemaProvider({ vendor: 'zod', t: zodNamespace, introspect: zodToNode });
+ * ```
+ */
+export function configureSchemaProvider(provider) {
+    active = provider;
+}
+export function schemaProvider() {
+    return active;
+}
+export function resetSchemaProvider() {
+    active = builtinProvider;
+}
+/**
+ * The IR for any schema, whoever built it. Throws `X_SCHEMA_UNSUPPORTED` rather than silently
+ * emitting an empty OpenAPI body.
+ */
+export function introspect(schema) {
+    const node = active.introspect?.(schema) ?? nodeOf(schema);
+    if (node === undefined) {
+        throw new SchemaUnsupportedError({
+            cause: `provider "${active.vendor}" cannot describe this schema as a SchemaNode`,
+            fix: 'add introspect() to the object passed to configureSchemaProvider()',
+            meta: { vendor: active.vendor },
+        });
+    }
+    return node;
+}
+/** Best-effort variant for callers that can degrade (HTTP query coercion). */
+export function tryIntrospect(schema) {
+    return active.introspect?.(schema) ?? nodeOf(schema);
+}
+//# sourceMappingURL=provider.js.map

package/src/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["provider.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,gGAAgG;AAChG,yFAAyF;AAEzF,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,MAAM,EAAmB,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAmB,MAAM,cAAc,CAAC;AAazD,MAAM,CAAC,MAAM,eAAe,GAAmB,MAAM,CAAC,MAAM,CAAC;IAC3D,MAAM,EAAE,UAAU;IAClB,CAAC,EAAE,QAAQ;IACX,UAAU,EAAE,MAAM;CACnB,CAAC,CAAC;AAEH,IAAI,MAAM,GAAmB,eAAe,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAwB;IAC9D,MAAM,GAAG,QAAQ,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,MAAM,GAAG,eAAe,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAe;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,sBAAsB,CAAC;YAC/B,KAAK,EAAE,aAAa,MAAM,CAAC,MAAM,+CAA+C;YAChF,GAAG,EAAE,oEAAoE;YACzE,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;SAChC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;AACvD,CAAC"}

package/src/provider.ts

@@ -0,0 +1,67 @@
+// Single responsibility: the swap point. One provider is active per process; everything that
+// consumes schemas (OpenAPI, MCP, coercion, the admin form generator) goes through `introspect`
+// so a third-party library can be plugged in without touching the rest of the framework.
+
+import { SchemaUnsupportedError } from './errors';
+import { nodeOf, type SchemaNode } from './node';
+import { builtinT, type TNamespace } from './validators';
+
+export interface SchemaProvider {
+  /** Matches `~standard.vendor`, e.g. `ultimate`, `arktype`, `zod`. */
+  readonly vendor: string;
+  readonly t: TNamespace;
+  /**
+   * Return the IR for one of this provider's schemas. Required for OpenAPI and MCP tool
+   * schemas; omit it only if the provider also supplies `toJsonSchema`.
+   */
+  introspect?(schema: unknown): SchemaNode | undefined;
+}
+
+export const builtinProvider: SchemaProvider = Object.freeze({
+  vendor: 'ultimate',
+  t: builtinT,
+  introspect: nodeOf,
+});
+
+let active: SchemaProvider = builtinProvider;
+
+/**
+ * Swap the library behind `t`.
+ *
+ * ```ts
+ * import { z } from 'zod';
+ * configureSchemaProvider({ vendor: 'zod', t: zodNamespace, introspect: zodToNode });
+ * ```
+ */
+export function configureSchemaProvider(provider: SchemaProvider): void {
+  active = provider;
+}
+
+export function schemaProvider(): SchemaProvider {
+  return active;
+}
+
+export function resetSchemaProvider(): void {
+  active = builtinProvider;
+}
+
+/**
+ * The IR for any schema, whoever built it. Throws `X_SCHEMA_UNSUPPORTED` rather than silently
+ * emitting an empty OpenAPI body.
+ */
+export function introspect(schema: unknown): SchemaNode {
+  const node = active.introspect?.(schema) ?? nodeOf(schema);
+  if (node === undefined) {
+    throw new SchemaUnsupportedError({
+      cause: `provider "${active.vendor}" cannot describe this schema as a SchemaNode`,
+      fix: 'add introspect() to the object passed to configureSchemaProvider()',
+      meta: { vendor: active.vendor },
+    });
+  }
+  return node;
+}
+
+/** Best-effort variant for callers that can degrade (HTTP query coercion). */
+export function tryIntrospect(schema: unknown): SchemaNode | undefined {
+  return active.introspect?.(schema) ?? nodeOf(schema);
+}

package/src/standard.d.ts

@@ -0,0 +1,44 @@
+import { type ValidationIssue } from './errors';
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaProps<Input, Output>;
+}
+export interface StandardSchemaProps<Input, Output> {
+    readonly version: 1;
+    /** Library name, e.g. `ultimate`, `arktype`, `zod`. */
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+    readonly types?: StandardTypes<Input, Output> | undefined;
+}
+export interface StandardTypes<Input, Output> {
+    readonly input: Input;
+    readonly output: Output;
+}
+export interface StandardSuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+}
+export interface StandardFailureResult {
+    readonly issues: readonly StandardIssue[];
+}
+export type StandardResult<Output> = StandardSuccessResult<Output> | StandardFailureResult;
+export interface StandardPathSegment {
+    readonly key: PropertyKey;
+}
+export interface StandardIssue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | StandardPathSegment)[] | undefined;
+}
+export type InferInput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['input'];
+export type InferOutput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['output'];
+/** `['items', 0, 'price']` -> `items[0].price` */
+export declare function formatPath(path: readonly (PropertyKey | StandardPathSegment)[] | undefined): string;
+/** Normalise any conforming library's issues into Ultimate's path-annotated shape. */
+export declare function toValidationIssues(issues: readonly StandardIssue[]): readonly ValidationIssue[];
+/** Validate against ANY conforming schema. Never throws on invalid input. */
+export declare function validate<S extends StandardSchemaV1>(schema: S, value: unknown): StandardResult<InferOutput<S>>;
+export declare function validateAsync<S extends StandardSchemaV1>(schema: S, value: unknown): Promise<StandardResult<InferOutput<S>>>;
+/** Validate or throw `X_VALIDATION_FAILED` with a path-annotated issue list. */
+export declare function parse<S extends StandardSchemaV1>(schema: S, value: unknown, root?: string): InferOutput<S>;
+export declare function parseAsync<S extends StandardSchemaV1>(schema: S, value: unknown, root?: string): Promise<InferOutput<S>>;
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+//# sourceMappingURL=standard.d.ts.map

package/src/standard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.d.ts","sourceRoot":"","sources":["standard.ts"],"names":[],"mappings":"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"}