@opensoftware/contracts 0.0.0-stage → 1.0.0

package/dist/generated/types.d.ts

@@ -0,0 +1,543 @@
+export type paths = Record<string, never>;
+export type webhooks = Record<string, never>;
+export type components = {
+    schemas: {
+        /** @description A person or trigger. RUNTIME-008: every run is attributed to one. */
+        Actor: {
+            kind: components["schemas"]["ActorKind"];
+            /** @description Stable ID in the source system, prefixed with the source, for example "slack:U024BE7LH". */
+            id: string;
+            /** @description Shown to people, for example "Varun". */
+            displayName?: string;
+        };
+        /**
+         * @description Who caused something: a person, or an automated trigger such as a cron rule or an alert.
+         * @enum {string}
+         */
+        ActorKind: "person" | "trigger";
+        Agent: {
+            description?: string;
+            /** @description Harness adapter, declared under `providers.harness`, for example "claude-code". */
+            harness: components["schemas"]["Name"];
+            /** @description A model ID or a routing alias of the inference gateway, for example "routes/triage". */
+            model: string;
+            /** @description Path to the Markdown prompt. */
+            prompt: string;
+            /** @description Repositories the agent operates on, as clone URLs or "<owner>/<name>". */
+            repositories?: string[];
+            /** @description MCP servers: `registry:<name>@<version>` or `<name>@<version>`. */
+            mcp?: string[];
+            /** @description Paths to skill folders. */
+            skills?: string[];
+            secrets?: components["schemas"]["SecretReference"][];
+            /** @description Runtime of the agent. */
+            sandbox?: components["schemas"]["Sandbox"];
+        };
+        Artifact: {
+            path: components["schemas"]["BundlePath"];
+            kind: components["schemas"]["ArtifactKind"];
+            /** @description IANA media type, for example "image/png". */
+            mediaType: string;
+            sha256: components["schemas"]["Sha256"];
+            bytes?: number;
+        };
+        /** @enum {string} */
+        ArtifactKind: "screenshot" | "video" | "playwright-trace" | "junit" | "log" | "report" | "other";
+        /**
+         * @description Starts the workflow, or the named job, on an event (`on`) or a schedule (`cron`). Exactly one of the two; a
+         *     schedule names its job. One model rather than a union, so every generated client reads it without guessing.
+         */
+        Automation: {
+            /** @description Event filter, for example "github.issue.labeled(auto-implement)" or "sentry.fatal". */
+            on?: string;
+            /** @description Five-field cron expression in UTC. */
+            cron?: string;
+            /** @description Job to run. Required with `cron`; without it an event starts the workflow. */
+            run?: components["schemas"]["Name"];
+        } & (unknown | unknown);
+        Benchmark: {
+            /** @description Path to the Harbor task suite. */
+            suite: string;
+            /** @description Five-field cron expression in UTC. Without it the suite runs on request. */
+            schedule?: string;
+        };
+        /** @description A path inside the bundle: relative, forward slashes, no "..". */
+        BundlePath: string;
+        /** @description A Git commit hash, abbreviated (7+) or full. The factory version is the commit of the factory definition. */
+        CommitHash: string;
+        /**
+         * @description `evidence.json` at the root of an evidence bundle: what was verified, against which scenario IDs, with which
+         *     artifacts and result (P10).
+         */
+        EvidenceManifest: {
+            /** @description Version of this format. */
+            manifestVersion: components["schemas"]["FormatVersion"];
+            id: components["schemas"]["Identifier"];
+            /** Format: date-time */
+            createdAt: string;
+            /** @description The change that was verified. */
+            subject: components["schemas"]["EvidenceSubject"];
+            runId?: components["schemas"]["Identifier"];
+            workItemId?: components["schemas"]["Identifier"];
+            /** @description The tool that wrote the bundle, for example proof 1.2.0. */
+            producer: components["schemas"]["Producer"];
+            /** @description Passed only when every scenario passed. */
+            result: components["schemas"]["VerificationResult"];
+            scenarios: components["schemas"]["ScenarioEvidence"][];
+            artifacts: components["schemas"]["Artifact"][];
+        };
+        /** @enum {string} */
+        EvidenceRequirement: "required" | "optional";
+        EvidenceSubject: {
+            /** Format: uri */
+            repository: string;
+            commit: components["schemas"]["CommitHash"];
+            /** Format: uri */
+            pullRequest?: string;
+        };
+        /**
+         * @description `factory.yaml`: the desired state of one factory (P3). Paths are relative to the file.
+         *     Realizes SCN-FACTORY-CODE-001: agents and prompts; MCP servers, skills and secrets per agent;
+         *     repositories; model and runtime; automations; scorers and benchmarks.
+         */
+        FactoryDefinition: {
+            /** @description Editors may point at this schema. Ignored by every tool. */
+            $schema?: string;
+            /** @description Version of this format. A new major version of the format gets a new value. */
+            version: components["schemas"]["FormatVersion"];
+            /** @description Name of the factory. */
+            factory: components["schemas"]["Name"];
+            description?: string;
+            /** @description Adapters per port with a version range, pinned in `factory.lock` by `factory plan`. */
+            providers?: components["schemas"]["Providers"];
+            /** @description Agents by name. */
+            agents: Record<string, never>;
+            /** @description Stages in order. Each stage runs one agent; the agent defaults to the stage name. */
+            workflow?: components["schemas"]["Stage"][];
+            /** @description What starts work without a person asking. */
+            automations?: components["schemas"]["Automation"][];
+            /** @description Scorers by name. */
+            scorers?: Record<string, never>;
+            /** @description Benchmark suites by name. */
+            benchmarks?: Record<string, never>;
+        };
+        /**
+         * @description The version of a format inside its documents. Only 1 exists; a new major version of a format adds the next.
+         * @constant
+         */
+        FormatVersion: 1;
+        Gate: {
+            /** @description Path to the Rego policy that decides or picks the approvers. */
+            policy: string;
+            /** @description Approver groups. The policy may narrow them. */
+            approvers?: components["schemas"]["Name"][];
+        };
+        /** @description gatekeeper: a gate was decided. */
+        GateDecided: {
+            /** @constant */
+            specversion: "1.0";
+            /** @description Unique per source. A consumer that sees the same source and id twice handles the event once. */
+            id: components["schemas"]["Identifier"];
+            /** @description The producing module, for example "/osf/intake". */
+            source: string;
+            /** @constant */
+            type: "gate.decided@v1";
+            /** Format: date-time */
+            time: string;
+            /** @description The ID of the thing the event is about: work item, gate, run, score or pull request. */
+            subject?: string;
+            /** @constant */
+            datacontenttype?: "application/json";
+            /** Format: uri */
+            dataschema?: string;
+            /** @description W3C trace context (CloudEvents distributed tracing extension). */
+            traceparent?: string;
+            data: components["schemas"]["GateDecidedData"];
+        };
+        GateDecidedData: {
+            gateId: components["schemas"]["Identifier"];
+            workItemId: components["schemas"]["Identifier"];
+            decision: components["schemas"]["GateDecision"];
+            /** @description The person who decided. Absent only when the gate expired. */
+            decidedBy?: components["schemas"]["Actor"];
+            /** Format: date-time */
+            decidedAt: string;
+            reason?: string;
+        };
+        /** @enum {string} */
+        GateDecision: "approved" | "rejected" | "expired";
+        /** @description gatekeeper: a decision is needed before a stage starts. */
+        GateRequested: {
+            /** @constant */
+            specversion: "1.0";
+            /** @description Unique per source. A consumer that sees the same source and id twice handles the event once. */
+            id: components["schemas"]["Identifier"];
+            /** @description The producing module, for example "/osf/intake". */
+            source: string;
+            /** @constant */
+            type: "gate.requested@v1";
+            /** Format: date-time */
+            time: string;
+            /** @description The ID of the thing the event is about: work item, gate, run, score or pull request. */
+            subject?: string;
+            /** @constant */
+            datacontenttype?: "application/json";
+            /** Format: uri */
+            dataschema?: string;
+            /** @description W3C trace context (CloudEvents distributed tracing extension). */
+            traceparent?: string;
+            data: components["schemas"]["GateRequestedData"];
+        };
+        GateRequestedData: {
+            gateId: components["schemas"]["Identifier"];
+            workItemId: components["schemas"]["Identifier"];
+            runId?: components["schemas"]["Identifier"];
+            /** @description The stage that waits. */
+            stage: components["schemas"]["Name"];
+            /** @description Path to the policy in the factory definition. */
+            policy: string;
+            /** @description Approver groups picked by the policy. */
+            approvers: components["schemas"]["Name"][];
+            /** @description What the approver is asked to decide, shown in the channel. */
+            summary: string;
+            links?: components["schemas"]["Link"][];
+            /** Format: date-time */
+            expiresAt?: string;
+        };
+        /** @description An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque. */
+        Identifier: string;
+        Link: {
+            /** Format: uri */
+            url: string;
+            title?: string;
+        };
+        /** @description A lowercase name: letters, digits and hyphens, starting with a letter. Agents, stages, adapters, sources. */
+        Name: string;
+        Origin: {
+            /** @description The channel or system, for example "slack", "github", "sentry", "cron", "mcp". */
+            source: components["schemas"]["Name"];
+            /**
+             * Format: uri
+             * @description Link back to the origin, for example the Slack thread. Absent for a schedule.
+             */
+            url?: string;
+            /** @description ID in the source system. */
+            externalId?: string;
+        };
+        /** @description forge adapters: the factory opened a pull request. */
+        PrOpened: {
+            /** @constant */
+            specversion: "1.0";
+            /** @description Unique per source. A consumer that sees the same source and id twice handles the event once. */
+            id: components["schemas"]["Identifier"];
+            /** @description The producing module, for example "/osf/intake". */
+            source: string;
+            /** @constant */
+            type: "pr.opened@v1";
+            /** Format: date-time */
+            time: string;
+            /** @description The ID of the thing the event is about: work item, gate, run, score or pull request. */
+            subject?: string;
+            /** @constant */
+            datacontenttype?: "application/json";
+            /** Format: uri */
+            dataschema?: string;
+            /** @description W3C trace context (CloudEvents distributed tracing extension). */
+            traceparent?: string;
+            data: components["schemas"]["PrOpenedData"];
+        };
+        PrOpenedData: {
+            /** Format: uri */
+            url: string;
+            /** Format: uri */
+            repository: string;
+            number: number;
+            title: string;
+            headBranch: string;
+            baseBranch: string;
+            headCommit: components["schemas"]["CommitHash"];
+            author: components["schemas"]["Actor"];
+            workItemId?: components["schemas"]["Identifier"];
+            runId?: components["schemas"]["Identifier"];
+        };
+        /** @enum {string} */
+        Priority: "urgent" | "high" | "normal" | "low";
+        Producer: {
+            name: string;
+            version: string;
+        };
+        /** @description The adapters a factory uses, per port (docs/architecture/internals.md). Keys are adapter names. */
+        Providers: {
+            harness?: Record<string, never>;
+            sandbox?: Record<string, never>;
+            channel?: Record<string, never>;
+            tracker?: Record<string, never>;
+            forge?: Record<string, never>;
+            inference?: Record<string, never>;
+            secrets?: Record<string, never>;
+            telemetry?: Record<string, never>;
+            policy?: Record<string, never>;
+        };
+        /** @description foreman: a run ended. */
+        RunCompleted: {
+            /** @constant */
+            specversion: "1.0";
+            /** @description Unique per source. A consumer that sees the same source and id twice handles the event once. */
+            id: components["schemas"]["Identifier"];
+            /** @description The producing module, for example "/osf/intake". */
+            source: string;
+            /** @constant */
+            type: "run.completed@v1";
+            /** Format: date-time */
+            time: string;
+            /** @description The ID of the thing the event is about: work item, gate, run, score or pull request. */
+            subject?: string;
+            /** @constant */
+            datacontenttype?: "application/json";
+            /** Format: uri */
+            dataschema?: string;
+            /** @description W3C trace context (CloudEvents distributed tracing extension). */
+            traceparent?: string;
+            data: components["schemas"]["RunCompletedData"];
+        };
+        RunCompletedData: {
+            runId: components["schemas"]["Identifier"];
+            workItemId: components["schemas"]["Identifier"];
+            stage?: components["schemas"]["Name"];
+            factoryVersion: components["schemas"]["CommitHash"];
+            outcome: components["schemas"]["RunOutcome"];
+            /** Format: date-time */
+            startedAt: string;
+            /** Format: date-time */
+            endedAt: string;
+            requester: components["schemas"]["Actor"];
+            source: components["schemas"]["Name"];
+            costUsd?: number;
+            traceId?: components["schemas"]["TraceId"];
+            pullRequests?: string[];
+            /** Format: uri */
+            evidenceBundle?: string;
+        };
+        /**
+         * @description How a run ended.
+         * @enum {string}
+         */
+        RunOutcome: "succeeded" | "failed" | "cancelled";
+        /**
+         * @description The attributes of one run: the OTel resource of every span of the run, and the attributes of its root
+         *     `invoke_agent` span. The run record travels as OTLP; this schema fixes the attribute names and types.
+         *     Realizes SCN-FACTORY-DATA-001 (record shape) and SCN-FACTORY-RUNTIME-008 (attribution).
+         */
+        RunRecord: {
+            resource: components["schemas"]["RunResource"];
+            span: components["schemas"]["RunSpan"];
+        };
+        /** @description Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run. */
+        RunResource: {
+            "service.name": string;
+            "osf.run.id": components["schemas"]["Identifier"];
+            "osf.work_item.id": components["schemas"]["Identifier"];
+            /** @description Commit of the factory definition the run used. */
+            "osf.factory.version": components["schemas"]["CommitHash"];
+            "osf.stage"?: components["schemas"]["Name"];
+            "osf.requester.kind": components["schemas"]["ActorKind"];
+            "osf.requester.id": string;
+            /** @description Where the run was started from, for example "slack", "github", "cli". */
+            "osf.source": components["schemas"]["Name"];
+            /** Format: uri */
+            "osf.origin.url"?: string;
+            /** @description Harness adapter, for example "claude-code". */
+            "osf.harness.name": components["schemas"]["Name"];
+            "osf.harness.version"?: string;
+        };
+        /** @description Attributes of the root span of the run. GenAI names where a convention exists. */
+        RunSpan: {
+            /** @constant */
+            "gen_ai.operation.name": "invoke_agent";
+            "gen_ai.provider.name"?: string;
+            "gen_ai.agent.name"?: string;
+            /** @description The harness session ID. */
+            "gen_ai.conversation.id"?: string;
+            "gen_ai.request.model"?: string;
+            "gen_ai.response.model"?: string;
+            "gen_ai.usage.input_tokens"?: number;
+            "gen_ai.usage.output_tokens"?: number;
+            "gen_ai.usage.cache_read.input_tokens"?: number;
+            "gen_ai.usage.cache_write.input_tokens"?: number;
+            "osf.outcome": components["schemas"]["RunOutcome"];
+            /** @description Cost of all model calls of the run, from the inference gateway. */
+            "osf.cost.usd"?: number;
+            /**
+             * Format: uri
+             * @description Full transcript, stored when the run ends.
+             */
+            "osf.transcript.uri"?: string;
+            /** @description Artifacts of the run: reports, screenshots, videos. */
+            "osf.artifact.uris"?: string[];
+            "osf.pull_request.urls"?: string[];
+            "osf.issue.urls"?: string[];
+            /** Format: uri */
+            "osf.evidence_bundle.uri"?: string;
+            /**
+             * Format: uri
+             * @description Agent Trace record with line attribution of the run's changes.
+             */
+            "osf.agent_trace.uri"?: string;
+        };
+        Sandbox: {
+            /** @description Sandbox template name, for example "node-24". */
+            template: string;
+            /** @description CPU cores. The smallest unit is 0.001 (one millicore). */
+            cpu?: number;
+            /** @description Kubernetes quantity, for example "8Gi". */
+            memory?: string;
+            /** @description Hostnames the sandbox may reach. Everything else is blocked. */
+            egress?: string[];
+        };
+        ScenarioEvidence: {
+            id: components["schemas"]["ScenarioId"];
+            result: components["schemas"]["ScenarioResult"];
+            /** @description Paths of the artifacts in this bundle that prove the scenario. */
+            artifacts: components["schemas"]["BundlePath"][];
+            summary?: string;
+        };
+        /** @description A scenario ID as checked by SPEC, for example SCN-PROOF-004. */
+        ScenarioId: string;
+        /** @enum {string} */
+        ScenarioResult: "passed" | "failed" | "skipped";
+        /**
+         * @description The result of one scorer on one run. The fields are a subset of Langfuse's create-score request
+         *     (POST /api/public/scores), so a score can be sent to Langfuse as is. Factory fields live in `metadata`.
+         */
+        Score: {
+            id: components["schemas"]["Identifier"];
+            /** @description Scorer name, for example "redundant-tests". */
+            name: string;
+            /** @description A number for NUMERIC, 0 or 1 for BOOLEAN, a string for CATEGORICAL. */
+            value: number | string;
+            dataType: components["schemas"]["ScoreDataType"];
+            /** @description Trace of the run (the OTel trace ID). */
+            traceId: components["schemas"]["TraceId"];
+            /** @description Span the score is about, when it is not the whole run. */
+            observationId?: string;
+            sessionId?: string;
+            /** @description The reason. */
+            comment?: string;
+            /** Format: date-time */
+            timestamp: string;
+            /** @description API for scorers, ANNOTATION for scores a person reviews. */
+            source?: components["schemas"]["ScoreSource"];
+            configId?: string;
+            environment?: string;
+            metadata: components["schemas"]["ScoreMetadata"];
+        };
+        /** @enum {string} */
+        ScoreDataType: "NUMERIC" | "BOOLEAN" | "CATEGORICAL";
+        ScoreMetadata: {
+            "osf.run.id": components["schemas"]["Identifier"];
+            "osf.scorer.version"?: string;
+            /** @description Judge model of an LLM scorer. */
+            "osf.judge.model"?: string;
+            /** @description Cost of the judge call. */
+            "osf.judge.cost.usd"?: number;
+        };
+        /** @description scorekit: a scorer scored a run. */
+        ScoreRecorded: {
+            /** @constant */
+            specversion: "1.0";
+            /** @description Unique per source. A consumer that sees the same source and id twice handles the event once. */
+            id: components["schemas"]["Identifier"];
+            /** @description The producing module, for example "/osf/intake". */
+            source: string;
+            /** @constant */
+            type: "score.recorded@v1";
+            /** Format: date-time */
+            time: string;
+            /** @description The ID of the thing the event is about: work item, gate, run, score or pull request. */
+            subject?: string;
+            /** @constant */
+            datacontenttype?: "application/json";
+            /** Format: uri */
+            dataschema?: string;
+            /** @description W3C trace context (CloudEvents distributed tracing extension). */
+            traceparent?: string;
+            data: components["schemas"]["Score"];
+        };
+        /** @enum {string} */
+        ScoreSource: "API" | "ANNOTATION";
+        Scorer: {
+            /** @description Path to the Markdown judge prompt. */
+            judge: string;
+            /** @description Share of runs to score, 0 to 1. Default 1. */
+            sample?: number;
+        };
+        /** @description A reference to a secret, resolved at the egress proxy, never in the sandbox: "ref:<provider>/<name>". */
+        SecretReference: string;
+        Sha256: string;
+        Stage: {
+            stage: components["schemas"]["Name"];
+            /** @description Agent that runs the stage. Defaults to the agent with the stage's name. */
+            agent?: components["schemas"]["Name"];
+            /** @description The stage waits for a decision before it starts. */
+            gate?: components["schemas"]["Gate"];
+            /** @description Whether the stage must produce an evidence bundle. */
+            evidence?: components["schemas"]["EvidenceRequirement"];
+        };
+        /** @description An OpenTelemetry trace ID: 32 lowercase hex characters. */
+        TraceId: string;
+        /** @enum {string} */
+        VerificationResult: "passed" | "failed";
+        /** @description A semver range of an adapter, for example "^2". */
+        VersionRange: string;
+        /** @description One unit of requested work: the `data` of a `work.received@v1` CloudEvent. */
+        WorkItem: {
+            id: components["schemas"]["Identifier"];
+            type: components["schemas"]["WorkItemType"];
+            title: string;
+            description?: string;
+            /** @description The person or trigger that asked for the work. */
+            requester: components["schemas"]["Actor"];
+            /** @description Where the work came from. */
+            origin: components["schemas"]["Origin"];
+            /** @description Requests with the same key become one work item, for example "github:acme/web#42". */
+            dedupeKey: string;
+            /** @description Product surface the work is about, for example "checkout". */
+            surface?: string;
+            /** @description Set by triage. */
+            priority?: components["schemas"]["Priority"];
+            /** @description Related material: an error report, a change, a document. */
+            links?: components["schemas"]["Link"][];
+        };
+        /** @enum {string} */
+        WorkItemType: "idea" | "bug" | "task" | "automation";
+        /** @description intake: a work item was accepted. */
+        WorkReceived: {
+            /** @constant */
+            specversion: "1.0";
+            /** @description Unique per source. A consumer that sees the same source and id twice handles the event once. */
+            id: components["schemas"]["Identifier"];
+            /** @description The producing module, for example "/osf/intake". */
+            source: string;
+            /** @constant */
+            type: "work.received@v1";
+            /** Format: date-time */
+            time: string;
+            /** @description The ID of the thing the event is about: work item, gate, run, score or pull request. */
+            subject?: string;
+            /** @constant */
+            datacontenttype?: "application/json";
+            /** Format: uri */
+            dataschema?: string;
+            /** @description W3C trace context (CloudEvents distributed tracing extension). */
+            traceparent?: string;
+            data: components["schemas"]["WorkItem"];
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+};
+export type $defs = Record<string, never>;
+export type operations = Record<string, never>;

package/dist/generated/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { type Format } from "./formats.ts";
+import type { components } from "./generated/types.ts";
+export { diff as breakingChanges, type Schema } from "./breaking.ts";
+export { FORMATS, type Format, formatNamed } from "./formats.ts";
+export type { components } from "./generated/types.ts";
+type Schemas = components["schemas"];
+export type FactoryDefinition = Schemas["FactoryDefinition"];
+export type WorkItem = Schemas["WorkItem"];
+export type RunRecord = Schemas["RunRecord"];
+export type EvidenceManifest = Schemas["EvidenceManifest"];
+export type Score = Schemas["Score"];
+export type WorkReceived = Schemas["WorkReceived"];
+export type RunCompleted = Schemas["RunCompleted"];
+export type GateRequested = Schemas["GateRequested"];
+export type GateDecided = Schemas["GateDecided"];
+export type ScoreRecorded = Schemas["ScoreRecorded"];
+export type PrOpened = Schemas["PrOpened"];
+/** One reason a document does not match its format. `path` is a JSON Pointer into the document. */
+export interface Problem {
+    path: string;
+    message: string;
+}
+/** The JSON Schema of a format, as published in `<path>/<name>.schema.json`. */
+export declare function schemaOf(format: Format | string): Record<string, unknown>;
+/** Every problem of the document; empty when it matches the format. */
+export declare function validate(format: Format | string, document: unknown): Problem[];
+/** True when the document matches the format, with its type narrowed. */
+export declare function isValid<T>(format: Format | string, document: unknown): document is T;

package/dist/index.js

@@ -0,0 +1,73 @@
+// @opensoftware/contracts: the types of the shared formats and a validator for each. Modules import only from here.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020, {} from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { formatNamed } from "./formats.js";
+export { diff as breakingChanges } from "./breaking.js";
+export { FORMATS, formatNamed } from "./formats.js";
+/** The package root: dist/ and src/ both sit one level below it, next to the schema folders. */
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const validators = new Map();
+/** The JSON Schema of a format, as published in `<path>/<name>.schema.json`. */
+export function schemaOf(format) {
+    const found = typeof format === "string" ? formatNamed(format) : format;
+    if (!found)
+        throw new Error(`Unknown format: ${String(format)}`);
+    return JSON.parse(readFileSync(join(ROOT, found.path, `${found.name}.schema.json`), "utf8"));
+}
+/** Every problem of the document; empty when it matches the format. */
+export function validate(format, document) {
+    const name = typeof format === "string" ? format : format.name;
+    let check = validators.get(name);
+    if (!check) {
+        // strictRequired is off: "exactly one of" rules use `not: { required: [...] }` on purpose.
+        const ajv = new Ajv2020.default({ allErrors: true, strict: true, strictRequired: false });
+        addFormats.default(ajv);
+        check = ajv.compile(schemaOf(format));
+        validators.set(name, check);
+    }
+    return check(document) ? [] : problems(check.errors ?? []);
+}
+/** True when the document matches the format, with its type narrowed. */
+export function isValid(format, document) {
+    return validate(format, document).length === 0;
+}
+const ALTERNATIVES = new Set(["anyOf", "oneOf"]);
+/** Ajv errors as one line per problem; the branches of a failed `anyOf` or `oneOf` collapse into one problem. */
+function problems(errors) {
+    const alternatives = errors.filter((error) => ALTERNATIVES.has(error.keyword)).map((error) => error.instancePath);
+    const insideAlternative = (error) => !ALTERNATIVES.has(error.keyword) &&
+        /\/(anyOf|oneOf)\//.test(error.schemaPath) &&
+        alternatives.some((path) => error.instancePath === path || error.instancePath.startsWith(`${path}/`));
+    const seen = new Set();
+    const out = [];
+    for (const error of errors) {
+        if (insideAlternative(error))
+            continue;
+        const problem = describe(error);
+        const key = `${problem.path} ${problem.message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(problem);
+    }
+    return out;
+}
+function describe(error) {
+    const child = (name) => `${error.instancePath}/${name.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+    switch (error.keyword) {
+        case "additionalProperties":
+            return { path: child(String(error.params.additionalProperty)), message: "unknown field" };
+        case "unevaluatedProperties":
+            return { path: child(String(error.params.unevaluatedProperty)), message: "unknown field" };
+        case "required":
+            return { path: child(String(error.params.missingProperty)), message: "missing required field" };
+        case "anyOf":
+        case "oneOf":
+            return { path: error.instancePath || "/", message: "must match exactly one of the allowed forms" };
+        default:
+            return { path: error.instancePath || "/", message: error.message ?? error.keyword };
+    }
+}

package/dist/roundtrip.d.ts

@@ -0,0 +1,3 @@
+export declare const CLIENTS: readonly ["typescript"];
+export type Client = (typeof CLIENTS)[number];
+export declare function roundtrip(_client: Client, dir: string): number;