@effected/schemastore-cli 0.10.0 → 0.12.0

package/AjvValidator.js

@@ -0,0 +1,103 @@
+import { KeywordFamilies, SchemaValidator, SchemaValidatorError, ValidationFinding } from "@effected/schemastore";
+import { Ajv } from "ajv";
+import ajvFormats from "ajv-formats";
+import { Effect, Layer } from "effect";
+
+//#region src/AjvValidator.ts
+const addFormats = ajvFormats.default;
+const MAX_KEYWORD_WALK_DEPTH = 256;
+const collectDeclaredKeywords = (node, into, depth) => {
+	if (depth >= MAX_KEYWORD_WALK_DEPTH || typeof node !== "object" || node === null) return;
+	if (Array.isArray(node)) {
+		for (const element of node) collectDeclaredKeywords(element, into, depth + 1);
+		return;
+	}
+	for (const [key, value] of Object.entries(node)) {
+		if (KeywordFamilies.isDeclared(key)) {
+			into.add(key);
+			continue;
+		}
+		collectDeclaredKeywords(value, into, depth + 1);
+	}
+};
+const findingFromAjvError = (error) => ValidationFinding.make({
+	path: error.instancePath,
+	message: error.message ?? "schema is not valid",
+	keyword: error.keyword
+});
+/**
+* The shipped `SchemaValidator` implementation: ajv strict mode over the
+* Draft-07 meta-schema, with every declared `KeywordFamilies` keyword and
+* the standard `ajv-formats` vocabulary registered.
+*
+* @remarks
+* Lives in the CLI, not the library, so `ajv` is a cost only the command
+* pays: `@effected/schemastore` owns the `SchemaValidator` contract
+* and its doubles, an application that imports it at runtime never pulls an
+* engine, and the `schemastore` command composes this layer at its edge. It
+* is exported for a program that drives `SchemaPipeline` itself and wants
+* the same verdict the command gives.
+*
+* `validate` checks the document against the Draft-07 meta-schema and then
+* compiles it, reporting BOTH as `ValidationFinding` values: meta-schema
+* failures keep ajv's structured `instancePath` and `keyword`, while a
+* rejection ajv raises by *throwing* becomes a root-pathed finding — both a
+* strict-mode compile failure and a declared keyword whose NAME ajv's own
+* grammar (`/^[a-z_$][a-z0-9_$:-]*$/i`) refuses, such as an `x-ai-*` key
+* carrying a dot or a space. The error channel stays reserved for the engine
+* failing as a mechanism (`SchemaValidatorError`).
+*
+* `strict` defaults to `true` — SchemaStore's gate. Each call builds its own
+* ajv instance, so documents sharing an `$id` never collide. Registering the
+* declared families keeps the engine's verdict consistent with
+* `DocumentLint`'s through the same predicate, so the two cannot drift; the
+* plugin's `formatMaximum` / `formatMinimum` limit keywords are deliberately
+* NOT registered, because the lint answers those as unknown keywords.
+*
+* @example
+* ```ts
+* import { SchemaValidator } from "@effected/schemastore";
+* import { AjvValidator } from "@effected/schemastore-cli";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const validator = yield* SchemaValidator;
+*   return yield* validator.validate({ type: "object" });
+* });
+*
+* Effect.runPromise(Effect.provide(program, AjvValidator.layer));
+* // => []
+* ```
+*
+* @public
+*/
+var AjvValidator = class {
+	constructor() {}
+	/** The engine, as a `SchemaValidator` layer. */
+	static layer = Layer.succeed(SchemaValidator, { validate: (document, options) => Effect.try({
+		try: () => {
+			const ajv = new Ajv({
+				strict: options?.strict ?? true,
+				allErrors: true
+			});
+			addFormats(ajv, { keywords: false });
+			const declared = /* @__PURE__ */ new Set();
+			collectDeclaredKeywords(document, declared, 0);
+			try {
+				for (const keyword of declared) ajv.addKeyword({ keyword });
+				if (!ajv.validateSchema(document)) return (ajv.errors ?? []).map(findingFromAjvError);
+				ajv.compile(document);
+			} catch (cause) {
+				return [ValidationFinding.make({
+					path: "",
+					message: cause instanceof Error ? cause.message : String(cause)
+				})];
+			}
+			return [];
+		},
+		catch: (cause) => SchemaValidatorError.make({ cause })
+	}) });
+};
+
+//#endregion
+export { AjvValidator };

package/ConfigLoader.js

@@ -1,5 +1,5 @@
-import { Effect, FileSystem, Path, Schema } from "effect";
 import { isSchemastoreConfig } from "@effected/schemastore";
+import { Effect, FileSystem, Path, Predicate, Schema } from "effect";
 import { createJiti } from "jiti";
 
 //#region src/ConfigLoader.ts
@@ -19,8 +19,9 @@ searched: Schema.Array(Schema.String) }) {
 /**
 * The config file exists but could not be turned into a `SchemastoreConfig`:
 * the module threw on import, its default export is not a `defineConfig(...)`
-* value, a `schemas` element is not `SchemaTarget`-shaped, or two outputs
-* resolve to one absolute path.
+* value, `outputDir`/`catalogPath` is not a string, a `schemas` element is
+* not resolved-schema-shaped (or its `target`, `catalog`, or a `frozen`
+* entry is not shaped), or two outputs resolve to one absolute path.
 *
 * @public
 */
@@ -34,24 +35,22 @@ var ConfigLoadError = class extends Schema.TaggedError()("ConfigLoadError", {
 };
 const jitiImport = (path) => createJiti(path, { interopDefault: true }).import(path);
 const describeCause = (cause) => cause instanceof Error ? cause.stack ?? cause.message : String(cause);
-const describeMalformedTarget = (schemas) => {
-	if (!Array.isArray(schemas)) return "schemas is not an array";
-	for (const [index, target] of schemas.entries()) {
-		const record = typeof target === "object" && target !== null ? target : void 0;
-		if (!(record !== void 0 && Schema.isSchema(record.schema) && typeof record.$id === "string" && typeof record.path === "string" && typeof record.published === "boolean")) return `schemas[${index}] is not a SchemaTarget (missing schema/$id/path/published)`;
-	}
-};
-const describeMalformedCatalog = (catalog) => {
-	if (!Array.isArray(catalog)) return "catalog is not an array";
-	for (const [index, entry] of catalog.entries()) {
-		const record = typeof entry === "object" && entry !== null ? entry : void 0;
-		const config = record !== void 0 && typeof record.config === "object" && record.config !== null ? record.config : void 0;
-		if (config === void 0 || typeof config.path !== "string") return `catalog[${index}] is not a catalog entry (missing config.path)`;
+const isTargetShaped = (target) => Predicate.isObject(target) && Schema.isSchema(target.schema) && typeof target.$id === "string" && typeof target.path === "string" && typeof target.published === "boolean";
+const isCatalogEntryShaped = (catalog) => Predicate.isObject(catalog) && typeof catalog.name === "string" && typeof catalog.description === "string" && Array.isArray(catalog.fileMatch) && typeof catalog.url === "string";
+const describeMalformed = (config) => {
+	if (typeof config.outputDir !== "string") return "outputDir is not a string";
+	if (typeof config.catalogPath !== "string") return "catalogPath is not a string";
+	if (!Array.isArray(config.schemas)) return "schemas is not an array";
+	for (const [index, schema] of config.schemas.entries()) {
+		if (!Predicate.isObject(schema) || typeof schema.name !== "string" || !Array.isArray(schema.frozen) || typeof schema.drift !== "string") return `schemas[${index}] is not a resolved schema (missing name/target/frozen/drift)`;
+		if (!isTargetShaped(schema.target)) return `schemas[${index}].target is not a SchemaTarget (missing schema/$id/path/published)`;
+		if (schema.catalog !== void 0 && !isCatalogEntryShaped(schema.catalog)) return `schemas[${index}].catalog is not a catalog entry (missing name/description/fileMatch/url)`;
+		for (const [j, frozen] of schema.frozen.entries()) if (!Predicate.isObject(frozen) || typeof frozen.version !== "string" || typeof frozen.path !== "string" || typeof frozen.$id !== "string" || typeof frozen.url !== "string") return `schemas[${index}].frozen[${j}] is not a frozen version (missing version/path/$id/url)`;
 	}
 };
 const describeDuplicatePath = (config) => {
 	const seen = /* @__PURE__ */ new Set();
-	const paths = [...config.schemas.map((target) => target.path), ...config.catalog.map((c) => c.config.path)];
+	const paths = [...config.schemas.flatMap((schema) => [schema.target.path, ...schema.frozen.map((f) => f.path)]), config.catalogPath];
 	for (const p of paths) {
 		if (seen.has(p)) return `output path "${p}" is declared twice after resolution`;
 		seen.add(p);
@@ -100,25 +99,30 @@ var ConfigLoader = class ConfigLoader {
 		}
 	});
 	/**
-	* Resolve every relative `path` in the config (schema targets and catalog
-	* entries) against `directory`; absolute paths are left alone. The result
-	* keeps the `defineConfig` brand.
+	* Resolve every relative `path` in the config (`outputDir`, `catalogPath`,
+	* each schema's current target, and every frozen predecessor) against
+	* `directory`; absolute paths are left alone. `defineConfig` already
+	* prefixes `outputDir` onto every target/frozen `path`, so resolving them
+	* against the config directory equals resolving against the resolved
+	* `outputDir`. The result keeps the `defineConfig` brand.
 	*/
 	static resolvePaths = Effect.fn("ConfigLoader.resolvePaths")(function* (config, directory) {
 		const path = yield* Path.Path;
 		const absolute = (p) => path.isAbsolute(p) ? p : path.resolve(directory, p);
 		return {
 			...config,
-			schemas: config.schemas.map((target) => ({
-				...target,
-				path: absolute(target.path)
-			})),
-			catalog: config.catalog.map((c) => ({
-				...c,
-				config: {
-					...c.config,
-					path: absolute(c.config.path)
-				}
+			outputDir: absolute(config.outputDir),
+			catalogPath: absolute(config.catalogPath),
+			schemas: config.schemas.map((schema) => ({
+				...schema,
+				target: {
+					...schema.target,
+					path: absolute(schema.target.path)
+				},
+				frozen: schema.frozen.map((f) => ({
+					...f,
+					path: absolute(f.path)
+				}))
 			}))
 		};
 	});
@@ -144,16 +148,11 @@ var ConfigLoader = class ConfigLoader {
 			path: configPath,
 			reason: "default export is not a defineConfig(...) value from @effected/schemastore"
 		}));
-		const malformed = describeMalformedTarget(exported.schemas);
+		const malformed = describeMalformed(exported);
 		if (malformed !== void 0) return yield* Effect.fail(new ConfigLoadError({
 			path: configPath,
 			reason: malformed
 		}));
-		const malformedCatalog = describeMalformedCatalog(exported.catalog);
-		if (malformedCatalog !== void 0) return yield* Effect.fail(new ConfigLoadError({
-			path: configPath,
-			reason: malformedCatalog
-		}));
 		const directory = path.dirname(configPath);
 		const config = yield* ConfigLoader.resolvePaths(exported, directory);
 		const duplicate = describeDuplicatePath(config);

package/README.md

@@ -5,9 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-The `schemastore` command: build and check SchemaStore-shaped JSON Schema documents from a `schemastore.config.ts`. It is the command-line companion to [`@effected/schemastore`](https://www.npmjs.com/package/@effected/schemastore), which owns the pipeline; this package ships the plumbing every consumer used to write by hand — flag parsing, the contract gate, the drift test — once, as a `bin`.
-
-It is not a library: nothing is importable from it. Every type a config file needs comes from `@effected/schemastore`, which the CLI declares as a peer so your config and the pipeline share one `effect` and one `@effected/schemastore` instance.
+The `schemastore` command: build and check SchemaStore-shaped JSON Schema documents from a `schemastore.config.ts`. It is the companion to [`@effected/schemastore`](https://www.npmjs.com/package/@effected/schemastore), which owns the pipeline and every type a config needs; this package ships the plumbing every consumer used to write by hand — the config loader, the drift policy, the frozen-label checks, the catalog file, exit codes, a GitHub step summary — once, as a `bin`. It is also where the validation engine lives: `AjvValidator`, ajv in strict mode, composed by the command and exported for a program that drives the pipeline itself, so the library stays free of ajv.
 
 > **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
 > development against a single pinned Effect v4 prerelease. Packages graduate to
@@ -23,64 +21,90 @@ It is not a library: nothing is importable from it. Every type a config file nee
 
 ## Install
 
-`@effected/schemastore` and `@effected/schemastore-cli` release together at one version; install them at the same version.
+The two packages release together at one version. The library is a regular dependency (the application reads its schema's identity from it at runtime); the command is a devDependency.
 
 ```bash
-npm install --save-dev @effected/schemastore-cli @effected/schemastore effect
+pnpm add @effected/schemastore effect
+pnpm add -D @effected/schemastore-cli
 ```
 
-```bash
-pnpm add -D @effected/schemastore-cli @effected/schemastore effect
-```
+`effect` and `@effected/schemastore` are peers of the command, so your config and the pipeline share one instance of each.
 
 ## Configure
 
-Create `schemastore.config.ts` (also `.mts`, `.js`, `.mjs`). The CLI finds it by walking upward from the working directory, or takes its path as a positional argument. Relative `path` values resolve against the config file's directory.
+Declare each schema's hosted identity once, in the application, next to the schema — the application writes `$schema` from it, and the config hands the same value to `defineConfig` so nothing is spelled twice:
 
 ```ts
-import { defineConfig, SchemaTarget } from "@effected/schemastore";
-import { ReleaseOutput, SCHEMA_URL } from "./src/schema/release-output.js";
+// src/schema/output.ts
+import { HostedSchema } from "@effected/schemastore";
+import { Schema } from "effect";
 
-export default defineConfig({
- schemas: [
-  SchemaTarget.make({
-   schema: ReleaseOutput,
-   $id: SCHEMA_URL,
-   name: "silk-release-action",
-   version: "5.0.0",
-   path: "schemas/silk-release-action-5.0.0.json",
-   published: true,
-   jsonSchema: { onExcessProperty: "error" },
-  }),
- ],
- catalog: [
-  {
-   name: "silk-release-action",
-   description: "Structured output of the silk-release GitHub Action",
-   fileMatch: ["silk-release-output.json"],
-   baseUrl: "https://raw.githubusercontent.com/savvy-web/silk-release-action/main/schemas",
-   path: "schemas/catalog-entry.json",
-  },
- ],
- drift: { policy: "semantic", onDrift: "error" },
+export const OUTPUT_SCHEMA_VERSION = "5.2";
+
+export const OutputSchemaIdentity = HostedSchema.github({
+  repo: "savvy-web/silk-release-action",
+  path: "schemas",
+  name: "silk-release-action.output",
+  versions: [OUTPUT_SCHEMA_VERSION],
+});
+
+export const ReleaseOutput = Schema.Struct({
+  $schema: Schema.Literal(OutputSchemaIdentity.$id),
+  status: Schema.Literals(["released", "skipped"]),
 });
 ```
 
-- `schemas` — at least one `SchemaTarget`; `published` (default `false`) marks a version other people depend on.
-- `catalog` — zero or more SchemaStore catalog entries; `versions` is derived from every versioned schema of that name. The entry's `url` and each `versions` value are derived as `<baseUrl>/<name>-<version>.json`, so every schema's `path` must sit directly under the directory `baseUrl` names and its `$id` must be that exact URL — the CLI does not yet cross-check them.
-- `drift` — the default policy for published schemas (`strict`, `semantic` or `allow`) and what drift means (`error` or `warn`). Defaults to `{ policy: "semantic", onDrift: "error" }`.
+```ts
+// schemastore.config.ts (also .mts, .js, .mjs; found by walking upward, or passed as the positional argument)
+import { defineConfig } from "@effected/schemastore";
+import { OutputSchemaIdentity, ReleaseOutput } from "./src/schema/output.js";
 
-Then add two scripts:
+export default defineConfig({
+  // Relative paths resolve against this file's directory.
+  outputDir: "schemas",
+  schemas: {
+    [OutputSchemaIdentity.name]: { schema: ReleaseOutput, hosted: OutputSchemaIdentity },
+  },
+});
+```
 
 ```json
 {
- "scripts": {
-  "schema:build": "schemastore build",
-  "schema:check": "schemastore check"
- }
+  "scripts": {
+    "schema:build": "schemastore build",
+    "schema:check": "schemastore check"
+  }
 }
 ```
 
+`schema:build` writes `schemas/5.2/silk-release-action.output-5.2.json`; `schema:check` in CI fails whenever a build would write anything. Bumping the version is one constant, and once a label has shipped it stays in `versions` as a frozen file the command verifies but never regenerates.
+
+A schema published to SchemaStore itself uses `HostedSchema.schemastore` and declares its catalog entry; the command assembles every entry into one `catalog.json`:
+
+```ts
+export default defineConfig({
+  outputDir: "schemas",
+  schemas: {
+    okfit: {
+      schema: OkfitConfig,
+      hosted: HostedSchema.schemastore({ name: "okfit", versions: ["1.0"] }),
+      published: true,
+      catalog: { description: "okfit configuration", fileMatch: ["okfit.toml", ".okfit.toml"] },
+    },
+  },
+});
+```
+
+### The entry contract
+
+- The key IS the schema's `name`; `$id`, the write `path` and every catalog URL derive from it and the identity. There is no `$id` override. With `hosted`, the key must equal `hosted.name` and `baseUrl` / `versions` / `current` / `layout` must not be spelled beside it; without `hosted`, spell those fields (and a top-level `baseUrl` default) and the command builds the identity for you.
+- `versions` lists every label the catalog advertises; `current` (default: the newest) is the one generated at `path` / `$id`. Every other label is **frozen**: it must exist on disk and declare the `$id` the config derives for it, or the build fails before anything is written (`FrozenVersionMissingError`, `FrozenVersionIdMismatchError`). A `repo` / `branch` / `path` / `baseUrl` change is therefore a re-publish event for every frozen label. Declare a single label on a first run; append the next only once the first has shipped.
+- `appendVersion` (default `true`) keeps SchemaStore's `-<version>` file suffix; `false` lets the version directory name the file alone (`schemas/6.0/output.json`) and requires the `"versioned"` layout. Like `baseUrl`, it belongs to `hosted` when that is given, and flipping it is a re-publish event for every frozen label.
+- `published` (default `false`) marks a version other people already depend on: an unpublished schema regenerates in place through any change, a published one is held to the drift policy.
+- `drift` (`strict` / `semantic` / `allow`, default `semantic`) and `onDrift` (`error` / `warn`) are top-level defaults; `drift`, `published`, `jsonSchema` and `rootAnnotations` may be set per entry. Objects are emitted closed (`additionalProperties: false`); `jsonSchema: { onExcessProperty: "ignore" }` reopens one document.
+- `catalog` is required under SchemaStore hosting and optional under a custom host; every entry lands in ONE file at `catalogPath` (default `<outputDir>/catalog.json`).
+- A typo'd key anywhere in the config is named and rejected, never ignored, and every issue on an entry is reported at once.
+
 ## Commands
 
 ```text
@@ -88,21 +112,36 @@ schemastore build [config] [--drift=strict|semantic|allow] [--on-drift=error|war
 schemastore check [config] [--drift=strict|semantic|allow] [--on-drift=error|warn] [--force] [--format=human|json]
 ```
 
-- `build` generates every schema, runs the gates (structural lints and ajv strict mode), applies the drift policy, and writes what passes — content-compared, so unchanged files are untouched — along with each catalog entry.
-- `check` is the identical walk with no writes: it reports what `build` would do under the same flags and exits under the same conditions. It is the CI gate, so it also fails (exit `1`) whenever a build would write anything — a committed schema or catalog entry that differs from what the config generates, or is missing, is stale; run `schemastore build` and commit the result.
-- `--drift` and `--on-drift` override the config's `drift` block for one run; `--force` is sugar for `--drift=allow` and nothing else — combined with an explicit non-`allow` `--drift` it is a usage error (exit 64), not a precedence question; `--force --drift=allow` is accepted.
-- `--format=json` emits one JSON document on stdout (config path, per-schema outcome, per-catalog-entry outcome, effective drift policy and its source); human text moves to stderr.
-- When `GITHUB_STEP_SUMMARY` is set, both commands append a markdown summary table.
+- Before anything is generated, every frozen label is verified — present on disk, and self-identified by the derived `$id`.
+- `build` generates every schema, runs the gates (the structural lint and ajv strict mode), applies the drift policy, and writes what passes — content-compared, so an unchanged file is untouched — plus the catalog file when any entry declares one.
+- `check` is the identical walk with no writes: it reports what `build` would do under the same flags and exits the same way, and also fails (exit `1`) whenever a build would write anything — a stale or missing document is fixed by running `schemastore build` and committing the result. A `catalog.json` left behind after the last `catalog` block was removed is reported `orphaned` and fails `check` the same way, but `build` never deletes it: delete the file by hand, or restore a `catalog` block.
+- `--drift` and `--on-drift` override the config for one run; `--force` is sugar for `--drift=allow` (combined with a different explicit `--drift` it is a usage error).
+- `--format=json` emits one JSON document on stdout (per-schema outcome and effective tolerance, the catalog outcome, `drift: { onDrift, policy? }`); human text moves to stderr. When `GITHUB_STEP_SUMMARY` is set, both commands append a markdown table.
+
+## The engine, as a library export
+
+The command validates with ajv in strict mode — SchemaStore's own gate — registering the keyword families `@effected/schemastore` declares and the standard `ajv-formats` vocabulary (formats only, never the `formatMaximum` family), one fresh instance per document. The same layer is this package's one export, for a program composing the pipeline directly:
+
+```ts
+import { SchemaFile, SchemaPipeline } from "@effected/schemastore";
+import { AjvValidator } from "@effected/schemastore-cli";
+import { NodeServices } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+
+const AppLayer = Layer.mergeAll(SchemaFile.layer, AjvValidator.layer).pipe(Layer.provide(NodeServices.layer));
+
+const program = SchemaPipeline.run(targets).pipe(Effect.provide(AppLayer));
+```
 
-An unpublished schema is never drift: a contract change at a pinned but unpublished version rewrites the file in place.
+Findings come back as values; the error channel carries `SchemaValidatorError` only when the engine fails as a mechanism.
 
 ## Exit codes
 
 | code | meaning |
 | ---- | -------------------------------------------------------------------------- |
 | 0 | success, including drift under `onDrift: warn` |
-| 1 | drift under `onDrift: error` (the error lists one line per drifting schema: `$id`, change, current and next version), a gate failure, or — for `check` — any document `build` would write |
-| 2 | config not found, failed to load, or failed `SchemastoreConfig` validation |
+| 1 | drift under `onDrift: error` (one line per drifting schema: `$id`, change, current and next version), a gate failure, a missing or mis-identified frozen version, or — for `check` — anything `build` would write |
+| 2 | config not found, failed to load, or failed `defineConfig` validation |
 | 3 | infrastructure failure |
 | 64 | usage error |
 

package/Report.js

@@ -3,32 +3,37 @@ const findingLine = (finding) => `  ${finding.label} at "${finding.path}": ${fin
 const blockingCount = (findings) => findings.filter((finding) => finding.severity === "warning").length;
 const suggestionClause = (schema) => schema.nextVersion !== void 0 && schema.nextVersion !== schema.version ? ` → suggest ${schema.nextVersion}` : "";
 const publishedClause = (schema) => schema.version !== void 0 ? ` at published ${schema.version}` : "";
+const policyClause = (schema, report) => report.policy === void 0 ? ` [policy ${schema.policy}]` : "";
+const frozenClause = (schema) => schema.frozen.length > 0 ? ` (frozen: ${schema.frozen.join(", ")})` : "";
 const schemaLines = (schema, report) => {
+	const suffix = `${policyClause(schema, report)}${frozenClause(schema)}`;
 	switch (schema.outcome) {
-		case "written": return [`written (${schema.change}) ${schema.path}`];
-		case "unchanged": return [`unchanged ${schema.path}`];
-		case "would-write": return [`would write (${schema.change}) ${schema.path}`];
-		case "drift": return [`DRIFT ${schema.change}${publishedClause(schema)}${suggestionClause(schema)} — ${schema.path}`];
-		case "held": return [`held (${report.gateFailed ? "gate failed elsewhere" : "drift elsewhere"}) ${schema.path}`];
-		case "gate-failed": return [`GATE FAILED ${schema.path} (${blockingCount(schema.findings)} blocking finding(s))`, ...schema.findings.map(findingLine)];
+		case "written": return [`written (${schema.change}) ${schema.path}${suffix}`];
+		case "unchanged": return [`unchanged ${schema.path}${suffix}`];
+		case "would-write": return [`would write (${schema.change}) ${schema.path}${suffix}`];
+		case "drift": return [`DRIFT ${schema.change}${publishedClause(schema)}${suggestionClause(schema)} — ${schema.path}${suffix}`];
+		case "held": return [`held (${report.gateFailed ? "gate failed elsewhere" : "drift elsewhere"}) ${schema.path}${suffix}`];
+		case "gate-failed": return [`GATE FAILED ${schema.path}${suffix} (${blockingCount(schema.findings)} blocking finding(s))`, ...schema.findings.map(findingLine)];
 		default: return schema.outcome;
 	}
 };
 const catalogLine = (entry) => {
 	switch (entry.outcome) {
-		case "written": return `written catalog ${entry.path}`;
-		case "unchanged": return `unchanged catalog ${entry.path}`;
-		case "would-write": return `would write catalog ${entry.path}`;
-		case "held": return `held catalog ${entry.path}`;
+		case "written": return `written catalog ${entry.path} (${entry.entries} entries)`;
+		case "unchanged": return `unchanged catalog ${entry.path} (${entry.entries} entries)`;
+		case "would-write": return `would write catalog ${entry.path} (${entry.entries} entries)`;
+		case "held": return `held catalog ${entry.path} (${entry.entries} entries)`;
+		case "orphaned": return `orphaned catalog ${entry.path} (no schema declares a catalog)`;
 		default: return entry.outcome;
 	}
 };
+const driftClause = (report) => `drift ${report.policy !== void 0 ? `${report.policy} (flag)` : "per schema (config)"}, on-drift ${report.onDrift}`;
 const summaryLine = (report) => {
 	const written = report.schemas.filter((schema) => schema.outcome === "written").length;
 	const unchanged = report.schemas.filter((schema) => schema.outcome === "unchanged").length;
 	const drift = report.schemas.filter((schema) => schema.verdict === "drift").length;
 	const gateFailed = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;
-	return `${report.schemas.length} schema(s): ${written} written, ${unchanged} unchanged, ${drift} drift, ${gateFailed} gate failed — drift policy ${report.drift.policy}/${report.drift.onDrift} (${report.drift.source})`;
+	return `${report.schemas.length} schema(s): ${written} written, ${unchanged} unchanged, ${drift} drift, ${gateFailed} gate failed — ${driftClause(report)}`;
 };
 const warningLine = (schema, report) => `warning: DRIFT ${schema.change}${publishedClause(schema)} ${report.mode === "build" ? "written" : "would write"} under --on-drift=warn — ${schema.path}`;
 const tableRow = (columns) => `| ${columns.join(" | ")} |`;
@@ -52,7 +57,7 @@ var Report = class {
 	static human(report) {
 		const lines = [];
 		for (const schema of report.schemas) lines.push(...schemaLines(schema, report));
-		for (const entry of report.catalog) lines.push(catalogLine(entry));
+		if (report.catalog !== void 0) lines.push(catalogLine(report.catalog));
 		lines.push(summaryLine(report));
 		return lines;
 	}
@@ -62,7 +67,7 @@ var Report = class {
 	* would be) written, so there is no drift to warn about.
 	*/
 	static warnings(report) {
-		if (report.drift.onDrift !== "warn" || report.gateFailed) return [];
+		if (report.onDrift !== "warn" || report.gateFailed) return [];
 		return report.schemas.filter((schema) => schema.verdict === "drift").map((schema) => warningLine(schema, report));
 	}
 	/** One JSON document, stable key order. */
@@ -71,20 +76,21 @@ var Report = class {
 			mode: report.mode,
 			configPath: report.configPath,
 			drift: {
-				policy: report.drift.policy,
-				onDrift: report.drift.onDrift,
-				source: report.drift.source
+				onDrift: report.onDrift,
+				...report.policy !== void 0 ? { policy: report.policy } : {}
 			},
 			schemas: report.schemas.map((schema) => ({
 				$id: schema.$id,
 				path: schema.path,
-				...schema.name !== void 0 ? { name: schema.name } : {},
+				name: schema.name,
 				...schema.version !== void 0 ? { version: schema.version } : {},
 				published: schema.published,
 				change: schema.change,
 				verdict: schema.verdict,
+				policy: schema.policy,
 				outcome: schema.outcome,
 				...schema.nextVersion !== void 0 ? { nextVersion: schema.nextVersion } : {},
+				...schema.frozen.length > 0 ? { frozen: schema.frozen } : {},
 				findings: schema.findings.map((finding) => ({
 					source: finding.source,
 					severity: finding.severity,
@@ -93,11 +99,11 @@ var Report = class {
 					message: finding.message
 				}))
 			})),
-			catalog: report.catalog.map((entry) => ({
-				name: entry.name,
-				path: entry.path,
-				outcome: entry.outcome
-			})),
+			...report.catalog !== void 0 ? { catalog: {
+				path: report.catalog.path,
+				entries: report.catalog.entries,
+				outcome: report.catalog.outcome
+			} } : {},
 			drifted: report.drifted,
 			gateFailed: report.gateFailed,
 			wrote: report.wrote
@@ -110,6 +116,7 @@ var Report = class {
 		lines.push(tableRow([
 			"schema",
 			"version",
+			"frozen",
 			"published",
 			"change",
 			"outcome"
@@ -118,26 +125,37 @@ var Report = class {
 			"---",
 			"---",
 			"---",
+			"---",
 			"---"
 		]));
 		for (const schema of report.schemas) lines.push(tableRow([
-			schema.name ?? schema.$id,
+			schema.name,
 			schema.version ?? "",
+			schema.frozen.join(", "),
 			schema.published ? "yes" : "no",
 			schema.change,
 			schema.outcome
 		]));
-		if (report.catalog.length > 0) {
-			lines.push("", tableRow(["catalog", "outcome"]), tableRow(["---", "---"]));
-			for (const entry of report.catalog) lines.push(tableRow([entry.name, entry.outcome]));
-		}
+		if (report.catalog !== void 0) lines.push("", tableRow([
+			"catalog",
+			"entries",
+			"outcome"
+		]), tableRow([
+			"---",
+			"---",
+			"---"
+		]), tableRow([
+			report.catalog.path,
+			String(report.catalog.entries),
+			report.catalog.outcome
+		]));
 		lines.push("");
 		if (report.gateFailed) {
 			const failed = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;
 			lines.push(`**Gate:** ${failed} schema(s) failed`);
 		} else if (report.drifted) {
 			const drifted = report.schemas.filter((schema) => schema.verdict === "drift").length;
-			lines.push(`**Drift:** ${drifted} schema(s) drifted under ${report.drift.policy}/${report.drift.onDrift}`);
+			lines.push(`**Drift:** ${drifted} schema(s) drifted — ${driftClause(report)}`);
 		} else lines.push("**Drift:** none");
 		lines.push("");
 		return lines.join("\n");

package/Runner.js

@@ -1,9 +1,86 @@
-import { Effect, FileSystem, Option, Path, Schema } from "effect";
 import { CanonicalJson, CatalogEntry, DriftPolicy, SchemaPipeline, SchemaVersioning } from "@effected/schemastore";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
 
 //#region src/Runner.ts
+/**
+* Indicates that one or more schemas advertise a version label (via
+* {@link ResolvedSchema.frozen}) whose file is missing on disk. Raised by
+* {@link Runner.run} before anything is generated — a build must never
+* publish a catalog pointing a frozen label at a 404. Every miss is
+* collected and reported at once, not just the first.
+*
+* @public
+*/
+var FrozenVersionMissingError = class extends Schema.TaggedError()("FrozenVersionMissingError", { 
+/** One entry per schema/version whose frozen file is missing or not a file. */
+missing: Schema.Array(Schema.Struct({
+	/** The schema's key in the config. */
+	name: Schema.String,
+	/** The missing frozen version label. */
+	version: Schema.String,
+	/** The path that does not exist. */
+	path: Schema.String
+})) }) {
+	get message() {
+		const lines = this.missing.map((entry) => `  schema "${entry.name}" version ${entry.version}: ${entry.path}`);
+		return `${this.missing.length} frozen version(s) advertised but not on disk; nothing was written.\n${lines.join("\n")}`;
+	}
+};
+/**
+* Indicates that one or more frozen files exist but do not declare the
+* `$id` their {@link ResolvedSchema.frozen} entry derives — the file is
+* absent an `$id`, declares a different one, or does not parse. Raised by
+* {@link Runner.run} before anything is generated: a frozen document is
+* the one file the derivation does not own, so it is the one place `$id`
+* and the advertised URL can still disagree (a `baseUrl` change leaves
+* every frozen file carrying the old host). Every mismatch is collected.
+*
+* @public
+*/
+var FrozenVersionIdMismatchError = class extends Schema.TaggedError()("FrozenVersionIdMismatchError", { 
+/** One entry per frozen file whose `$id` is not the derived one. */
+mismatched: Schema.Array(Schema.Struct({
+	/** The schema's key in the config. */
+	name: Schema.String,
+	/** The frozen version label. */
+	version: Schema.String,
+	/** The frozen file. */
+	path: Schema.String,
+	/** The `$id` the config derives for this label. */
+	expected: Schema.String,
+	/** The `$id` the file declares; absent when it declares none or does not parse. */
+	actual: Schema.optionalKey(Schema.String),
+	/** Why the file fails: a different `$id`, no `$id` at all, or text that is not JSON. */
+	reason: Schema.Literals([
+		"mismatch",
+		"absent",
+		"unparseable"
+	])
+})) }) {
+	get message() {
+		const lines = this.mismatched.map((entry) => {
+			const detail = entry.reason === "mismatch" ? `declares $id ${entry.actual}, expected ${entry.expected}` : entry.reason === "absent" ? `declares no $id, expected ${entry.expected}` : `does not parse as JSON, expected $id ${entry.expected}`;
+			return `  schema "${entry.name}" version ${entry.version}: ${entry.path} ${detail}`;
+		});
+		return `${this.mismatched.length} frozen version(s) on disk do not carry their derived $id; nothing was written.\n${lines.join("\n")}`;
+	}
+};
 const pipelineOptions = { contractChanges: "allow" };
-const catalogText = (target) => CanonicalJson.serialize(Schema.encodeSync(CatalogEntry)(target.entry));
+const orNone = (read) => read.pipe(Effect.map(Option.some), Effect.catchIf((error) => error.reason._tag === "NotFound", () => Effect.succeed(Option.none())));
+const pendingOutcome = (wouldWrite, refused) => !wouldWrite ? "unchanged" : refused ? "held" : "would-write";
+const declaredId = (text) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return { reason: "unparseable" };
+	}
+	const $id = typeof parsed === "object" && parsed !== null ? parsed.$id : void 0;
+	return typeof $id === "string" ? {
+		reason: "ok",
+		$id
+	} : { reason: "absent" };
+};
 const parsesEqual = (existing, text) => {
 	try {
 		return CanonicalJson.equals(JSON.parse(existing), JSON.parse(text));
@@ -12,25 +89,43 @@ const parsesEqual = (existing, text) => {
 	}
 };
 /**
-* The shared `build` / `check` walk: classify every schema through
-* {@link DriftPolicy} over `SchemaPipeline.check`, then write through
-* `SchemaPipeline.run` only when nothing is refused.
+* The shared `build` / `check` walk: verify every advertised frozen version
+* exists, classify every current target through {@link DriftPolicy} over
+* `SchemaPipeline.check`, then write through `SchemaPipeline.run` only when
+* nothing is refused.
 *
 * @remarks
-* A build writes NOTHING when any schema fails its gate, or when any schema
-* drifts under `onDrift: "error"` — a partial write would leave a
-* repository half-bumped. Every otherwise-writable schema then reports
-* `held`, so a reader sees why a clean schema was not written — in both
-* modes, since `check` reports what `build` would do under the same
-* flags. Both modes share one `SchemaFile`; the single `writing`
-* predicate (`mode === "build" && !refused`) gates every write, schemas
-* and catalog entries alike. Under `onDrift: "warn"` drifting schemas are
-* written and keep their `"drift"` verdict for the renderer to shout
-* about.
+* **The frozen check runs first, before anything is generated.** Every
+* schema's {@link ResolvedSchema.frozen} versions are walked, and every miss
+* is reported at once: a build fails typed with
+* {@link FrozenVersionMissingError} listing every label with no file on disk
+* — nothing is written — a catalog that points a label at a 404 is a worse
+* failure than an early refusal. A file that is there is read, and must
+* declare the `$id` its entry derives, else the run fails typed with
+* {@link FrozenVersionIdMismatchError} (a different `$id`, none, or text
+* that is not JSON) — a `baseUrl` change is a re-publish event for every
+* frozen label, not a silent re-advertisement.
 *
-* Catalog entries follow the schemas: serialized canonically, compared by
-* parsed content against the file on disk, written only when different and
-* only when the run is writing.
+* **Drift is classified per schema, under that schema's own
+* {@link ResolvedSchema.drift} tolerance — unless `options.policy` is set,
+* in which case it overrides every schema's own for this run** (the `--drift`
+* / `--force` flags). A build writes NOTHING when any schema fails its gate,
+* or when any schema drifts under `onDrift: "error"` — a partial write would
+* leave a repository half-bumped. Every otherwise-writable schema then
+* reports `held`, so a reader sees why a clean schema was not written — in
+* both modes, since `check` reports what `build` would do under the same
+* flags. Both modes share one `SchemaFile`; the single `writing` predicate
+* (`mode === "build" && !refused`) gates every write, schemas and the
+* catalog file alike. Under `onDrift: "warn"` drifting schemas are written
+* and keep their `"drift"` verdict for the renderer to shout about.
+*
+* **Every catalog entry the config declares lands in ONE file** at
+* `config.catalogPath` — never one file per schema — serialized canonically
+* and compared by parsed content against the file on disk, written only
+* when different and only when the run is writing. When no schema declares
+* one, nothing is written; a file still at `catalogPath` is reported
+* `orphaned` (stale under `check`) and left in place, and the report omits
+* `catalog` entirely only when there is no such file either.
 *
 * @public
 */
@@ -39,79 +134,118 @@ var Runner = class {
 	static run = Effect.fn("Runner.run")(function* (config, options) {
 		const fs = yield* FileSystem.FileSystem;
 		const path = yield* Path.Path;
-		const checks = yield* SchemaPipeline.check(config.schemas, pipelineOptions);
+		const missing = [];
+		const mismatched = [];
+		for (const schema of config.schemas) for (const frozen of schema.frozen) {
+			const info = yield* orNone(fs.stat(frozen.path));
+			if (Option.isNone(info) || info.value.type !== "File") {
+				missing.push({
+					name: schema.name,
+					version: frozen.version,
+					path: frozen.path
+				});
+				continue;
+			}
+			const text = yield* fs.readFileString(frozen.path);
+			const declared = declaredId(text);
+			if (declared.reason !== "ok") mismatched.push({
+				name: schema.name,
+				version: frozen.version,
+				path: frozen.path,
+				expected: frozen.$id,
+				reason: declared.reason
+			});
+			else if (declared.$id !== frozen.$id) mismatched.push({
+				name: schema.name,
+				version: frozen.version,
+				path: frozen.path,
+				expected: frozen.$id,
+				actual: declared.$id,
+				reason: "mismatch"
+			});
+		}
+		if (missing.length > 0) return yield* Effect.fail(new FrozenVersionMissingError({ missing }));
+		if (mismatched.length > 0) return yield* Effect.fail(new FrozenVersionIdMismatchError({ mismatched }));
+		const targets = config.schemas.map((schema) => schema.target);
+		const checks = yield* SchemaPipeline.check(targets, pipelineOptions);
 		const gateFailed = checks.some((check) => check.blocked);
 		const classified = checks.map((check, i) => {
-			const target = config.schemas[i];
+			const schema = config.schemas[i];
+			const target = schema.target;
+			const policy = options.policy ?? schema.drift;
 			return {
+				schema,
 				target,
 				check,
 				verdict: DriftPolicy.classify({
 					published: target.published,
 					change: check.change
-				}, options.drift.policy),
+				}, policy),
+				policy,
 				nextVersion: target.version !== void 0 && check.change === "contract" && SchemaVersioning.isPinned(target.version) ? SchemaVersioning.next(target.version, "contract") : void 0
 			};
 		});
 		const drifted = classified.some((entry) => entry.verdict === "drift");
-		const refused = gateFailed || drifted && options.drift.onDrift === "error";
+		const refused = gateFailed || drifted && options.onDrift === "error";
 		const writing = options.mode === "build" && !refused;
-		const written = writing ? yield* SchemaPipeline.run(config.schemas, pipelineOptions).pipe(Effect.catchTags({
+		const written = writing ? yield* SchemaPipeline.run(targets, pipelineOptions).pipe(Effect.catchTags({
 			SchemaGateError: (error) => Effect.die(error),
 			SchemaContractChangeError: (error) => Effect.die(error)
 		})) : void 0;
-		const schemas = classified.map(({ target, check, verdict, nextVersion }, i) => {
-			const outcome = check.blocked ? "gate-failed" : written !== void 0 ? written[i].outcome : verdict === "drift" ? "drift" : refused && check.wouldWrite ? "held" : check.wouldWrite ? "would-write" : "unchanged";
+		const schemas = classified.map(({ schema, target, check, verdict, policy, nextVersion }, i) => {
+			const outcome = check.blocked ? "gate-failed" : written !== void 0 ? written[i].outcome : verdict === "drift" ? "drift" : pendingOutcome(check.wouldWrite, refused);
 			return {
 				$id: target.$id,
 				path: target.path,
+				name: schema.name,
 				published: target.published,
 				change: check.change,
 				verdict,
+				policy,
 				outcome,
 				findings: check.findings,
-				...target.name !== void 0 ? { name: target.name } : {},
+				frozen: schema.frozen.map((frozen) => frozen.version),
 				...target.version !== void 0 ? { version: target.version } : {},
 				...nextVersion !== void 0 ? { nextVersion } : {}
 			};
 		});
-		const catalog = [];
-		for (const entry of config.catalog) {
-			const { name, path: file } = entry.config;
-			const text = yield* catalogText(entry);
-			const existing = yield* fs.readFileString(file).pipe(Effect.map(Option.some), Effect.catchIf((error) => error.reason._tag === "NotFound", () => Effect.succeed(Option.none())));
-			if (Option.isSome(existing) && parsesEqual(existing.value, text)) catalog.push({
-				name,
-				path: file,
-				outcome: "unchanged"
-			});
-			else if (!writing) catalog.push({
-				name,
-				path: file,
-				outcome: refused ? "held" : "would-write"
-			});
-			else {
-				yield* fs.makeDirectory(path.dirname(file), { recursive: true });
-				yield* fs.writeFileString(file, text);
-				catalog.push({
-					name,
-					path: file,
-					outcome: "written"
-				});
+		const entries = config.schemas.flatMap((schema) => schema.catalog !== void 0 ? [schema.catalog] : []);
+		let catalog;
+		if (entries.length === 0) {
+			const info = yield* orNone(fs.stat(config.catalogPath));
+			if (Option.isSome(info)) catalog = {
+				path: config.catalogPath,
+				entries: 0,
+				outcome: "orphaned"
+			};
+		} else {
+			const text = yield* CanonicalJson.serialize(entries.map((entry) => Schema.encodeSync(CatalogEntry)(entry)));
+			const existing = yield* orNone(fs.readFileString(config.catalogPath));
+			const same = Option.isSome(existing) && parsesEqual(existing.value, text);
+			const outcome = writing && !same ? "written" : pendingOutcome(!same, refused);
+			if (outcome === "written") {
+				yield* fs.makeDirectory(path.dirname(config.catalogPath), { recursive: true });
+				yield* fs.writeFileString(config.catalogPath, text);
 			}
+			catalog = {
+				path: config.catalogPath,
+				entries: entries.length,
+				outcome
+			};
 		}
 		return {
 			mode: options.mode,
 			configPath: options.configPath,
-			drift: options.drift,
+			onDrift: options.onDrift,
+			...options.policy !== void 0 ? { policy: options.policy } : {},
 			schemas,
-			catalog,
+			...catalog !== void 0 ? { catalog } : {},
 			drifted,
 			gateFailed,
-			wrote: schemas.some((s) => s.outcome === "written") || catalog.some((c) => c.outcome === "written")
+			wrote: schemas.some((s) => s.outcome === "written") || catalog?.outcome === "written"
 		};
 	});
 };
 
 //#endregion
-export { Runner };
+export { FrozenVersionIdMismatchError, FrozenVersionMissingError, Runner };

package/cli/execute.js

@@ -1,10 +1,11 @@
+import { AjvValidator } from "../AjvValidator.js";
 import { ConfigLoader } from "../ConfigLoader.js";
 import { Report } from "../Report.js";
 import { Runner } from "../Runner.js";
 import { StepSummary } from "../StepSummary.js";
-import { CliRuntime } from "@effected/cli";
+import { SchemaFile } from "@effected/schemastore";
 import { Console, Effect, Option, Schema } from "effect";
-import { SchemaFile, SchemaValidator } from "@effected/schemastore";
+import { CliRuntime } from "@effected/cli";
 
 //#region src/cli/execute.ts
 const DriftedSchema = Schema.Struct({
@@ -67,11 +68,11 @@ var ConflictingFlagsError = class extends Schema.TaggedError()("ConflictingFlags
 		return `--force conflicts with --drift=${this.policy}: --force means --drift=allow`;
 	}
 };
-const effectiveDrift = (configured, input) => {
+const effectiveDrift = (config, input) => {
+	const forced = input.force ? "allow" : Option.getOrUndefined(input.drift);
 	return {
-		policy: input.force ? "allow" : Option.getOrElse(input.drift, () => configured.policy),
-		onDrift: Option.getOrElse(input.onDrift, () => configured.onDrift),
-		source: input.force || Option.isSome(input.drift) || Option.isSome(input.onDrift) ? "flag" : "config"
+		onDrift: Option.getOrElse(input.onDrift, () => config.onDrift),
+		...forced !== void 0 ? { policy: forced } : {}
 	};
 };
 const emit = Effect.fn("schemastore.emit")(function* (report, format) {
@@ -105,13 +106,16 @@ const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
 		...Option.isSome(input.config) ? { explicit: input.config.value } : {},
 		...deps.importModule !== void 0 ? { importModule: deps.importModule } : {}
 	});
-	const drift = effectiveDrift(loaded.config.drift, input);
+	const drift = effectiveDrift(loaded.config, input);
 	if (input.force) yield* Effect.logWarning(`--force: drift policy is allow for this run; a published document ${mode === "check" ? "would be" : "may be"} rewritten in place, which breaks every consumer pinned to its URL.`);
 	const report = yield* Runner.run(loaded.config, {
 		mode,
 		configPath: loaded.path,
-		drift
-	}).pipe(Effect.provide(SchemaFile.layer), Effect.provide(deps.validator ?? SchemaValidator.layer));
+		...drift
+	}).pipe(Effect.provide(SchemaFile.layer), Effect.provide(deps.validator ?? AjvValidator.layer), Effect.catchTags({
+		FrozenVersionMissingError: (error) => Effect.fail(CliRuntime.reported(error, 1)),
+		FrozenVersionIdMismatchError: (error) => Effect.fail(CliRuntime.reported(error, 1))
+	}));
 	yield* emit(report, input.format);
 	yield* StepSummary.append(Report.markdown(report));
 	if (report.gateFailed) {
@@ -128,7 +132,7 @@ const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
 		return yield* Effect.fail(CliRuntime.reported(new DriftError({ drifted }), 1));
 	}
 	if (mode === "check") {
-		const count = report.schemas.filter((schema) => schema.outcome === "would-write").length + report.catalog.filter((entry) => entry.outcome === "would-write").length;
+		const count = report.schemas.filter((schema) => schema.outcome === "would-write").length + (report.catalog?.outcome === "would-write" || report.catalog?.outcome === "orphaned" ? 1 : 0);
 		if (count > 0) return yield* Effect.fail(CliRuntime.reported(new StaleError({ count }), 1));
 	}
 });

package/cli/flags.js

@@ -17,13 +17,13 @@ const driftFlag = Flag.Literals("drift", [
 	"strict",
 	"semantic",
 	"allow"
-]).pipe(Flag.withDescription("Drift tolerance for published schemas; overrides the config's drift.policy"), Flag.optional);
+]).pipe(Flag.withDescription("Drift tolerance for published schemas; overrides every schema's drift"), Flag.optional);
 /**
 * `--on-drift`: what drift does, overriding the config.
 *
 * @public
 */
-const onDriftFlag = Flag.Literals("on-drift", ["error", "warn"]).pipe(Flag.withDescription("What drift does: refuse every write (error) or write and warn; overrides drift.onDrift"), Flag.optional);
+const onDriftFlag = Flag.Literals("on-drift", ["error", "warn"]).pipe(Flag.withDescription("What drift does: refuse every write (error) or write and warn; overrides the config's onDrift"), Flag.optional);
 /**
 * `--force`: shorthand for `--drift=allow`.
 *

package/cli/program.js

@@ -1,7 +1,7 @@
 import { ConfigLoadError } from "../ConfigLoader.js";
 import { makeCommands } from "./root.js";
-import { CliLogger, CliRuntime } from "@effected/cli";
 import { Effect } from "effect";
+import { CliLogger, CliRuntime } from "@effected/cli";
 import { Command } from "effect/unstable/cli";
 
 //#region src/cli/program.ts

package/index.d.ts

@@ -0,0 +1,56 @@
+import { SchemaValidator } from "@effected/schemastore";
+import { Layer } from "effect";
+//#region src/AjvValidator.d.ts
+/**
+ * The shipped `SchemaValidator` implementation: ajv strict mode over the
+ * Draft-07 meta-schema, with every declared `KeywordFamilies` keyword and
+ * the standard `ajv-formats` vocabulary registered.
+ *
+ * @remarks
+ * Lives in the CLI, not the library, so `ajv` is a cost only the command
+ * pays: `@effected/schemastore` owns the `SchemaValidator` contract
+ * and its doubles, an application that imports it at runtime never pulls an
+ * engine, and the `schemastore` command composes this layer at its edge. It
+ * is exported for a program that drives `SchemaPipeline` itself and wants
+ * the same verdict the command gives.
+ *
+ * `validate` checks the document against the Draft-07 meta-schema and then
+ * compiles it, reporting BOTH as `ValidationFinding` values: meta-schema
+ * failures keep ajv's structured `instancePath` and `keyword`, while a
+ * rejection ajv raises by *throwing* becomes a root-pathed finding — both a
+ * strict-mode compile failure and a declared keyword whose NAME ajv's own
+ * grammar (`/^[a-z_$][a-z0-9_$:-]*$/i`) refuses, such as an `x-ai-*` key
+ * carrying a dot or a space. The error channel stays reserved for the engine
+ * failing as a mechanism (`SchemaValidatorError`).
+ *
+ * `strict` defaults to `true` — SchemaStore's gate. Each call builds its own
+ * ajv instance, so documents sharing an `$id` never collide. Registering the
+ * declared families keeps the engine's verdict consistent with
+ * `DocumentLint`'s through the same predicate, so the two cannot drift; the
+ * plugin's `formatMaximum` / `formatMinimum` limit keywords are deliberately
+ * NOT registered, because the lint answers those as unknown keywords.
+ *
+ * @example
+ * ```ts
+ * import { SchemaValidator } from "@effected/schemastore";
+ * import { AjvValidator } from "@effected/schemastore-cli";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const validator = yield* SchemaValidator;
+ *   return yield* validator.validate({ type: "object" });
+ * });
+ *
+ * Effect.runPromise(Effect.provide(program, AjvValidator.layer));
+ * // => []
+ * ```
+ *
+ * @public
+ */
+export declare class AjvValidator {
+  private constructor();
+  /** The engine, as a `SchemaValidator` layer. */
+  static readonly layer: Layer.Layer<SchemaValidator>;
+}
+//#endregion
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,3 @@
+import { AjvValidator } from "./AjvValidator.js";
+
+export { AjvValidator };

package/main.js

@@ -1,8 +1,8 @@
 import { loggerLayer, program } from "./cli/program.js";
+import { Effect } from "effect";
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { CliRuntime } from "@effected/cli";
-import { Effect } from "effect";
 import { CliError } from "effect/unstable/cli";
 
 //#region src/main.ts
@@ -15,7 +15,7 @@ const render = (error) => CliError.isCliError(error) && error._tag === "ShowHelp
 const main = () => {
 	const run = program(process.argv.slice(2), {
 		cwd: process.cwd(),
-		version: "0.10.0"
+		version: "0.12.0"
 	}).pipe(Effect.provide(NodeServices.layer), CliRuntime.reportFailures({
 		exitCode: 3,
 		render

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore-cli",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"private": false,
 	"description": "The schemastore command: build and check SchemaStore-shaped JSON Schema documents from a schemastore.config.ts, with a per-schema published flag and a drift policy.",
 	"keywords": [
@@ -29,6 +29,11 @@
 	"sideEffects": false,
 	"type": "module",
 	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"bin": {
@@ -37,10 +42,12 @@
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-rc.115",
 		"@effected/cli": "^0.5.1",
+		"ajv": "^8.20.0",
+		"ajv-formats": "^3.0.1",
 		"jiti": "^2.6.0"
 	},
 	"peerDependencies": {
-		"@effected/schemastore": "0.10.0",
+		"@effected/schemastore": "0.12.0",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.1"
+    }
+  ]
+}