@effected/schemastore-cli 0.11.0 → 0.13.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, Predicate, Schema } from "effect";
 import { isSchemastoreConfig } from "@effected/schemastore";
+import { Effect, FileSystem, Path, Predicate, Schema } from "effect";
 import { createJiti } from "jiti";
 
 //#region src/ConfigLoader.ts
@@ -45,7 +45,7 @@ const describeMalformed = (config) => {
 		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.url !== "string") return `schemas[${index}].frozen[${j}] is not a frozen version (missing version/path/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) => {

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,57 +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
+// src/schema/output.ts
+import { HostedSchema } from "@effected/schemastore";
+import { Schema } from "effect";
+
+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"]),
+});
+```
 
 ```ts
+// schemastore.config.ts (also .mts, .js, .mjs; found by walking upward, or passed as the positional argument)
 import { defineConfig } from "@effected/schemastore";
-import { OkfitConfig } from "./src/config-schema.js";
+import { OutputSchemaIdentity, ReleaseOutput } from "./src/schema/output.js";
 
 export default defineConfig({
- outputDir: "schemas",
- baseUrl: "schemastore",
- schemas: {
-  okfit: {
-   schema: OkfitConfig,
-   versions: ["1.0"],
-   published: true,
-   catalog: { description: "okfit configuration", fileMatch: ["okfit.toml", ".okfit.toml"] },
+  // Relative paths resolve against this file's directory.
+  outputDir: "schemas",
+  schemas: {
+    [OutputSchemaIdentity.name]: { schema: ReleaseOutput, hosted: OutputSchemaIdentity },
   },
- },
 });
 ```
 
-A second label is appended to `versions` only once the first is published
-and its file already exists on disk — see "The lifecycle" in the
-`building-schemastore-schemas` skill's `drift-and-versioning.md` reference.
-A first-run config should declare a single label; naming an extra one before
-its file exists fails the build with `FrozenVersionMissingError`.
-
-`schemas` is keyed by file base name — the key IS the schema's `name`, and `$id`, the write `path` and every catalog URL derive from it, `outputDir` and `baseUrl`; there is no `$id` override. `versions` lists every label the catalog advertises; `current` (default: the newest) is the one generated at `path`/`$id`, and every other label becomes a **frozen** file the CLI verifies still exists on disk but never regenerates — advertising a frozen label with nothing on disk fails the build before anything is written. `published` (default `false`) marks a version other people already depend on. `baseUrl: "schemastore"` expands `$id` to `https://json.schemastore.org/…` and the catalog URL to `https://www.schemastore.org/…`; any other value is one `https://` base for both. `outputDir` and `onDrift` are top-level only; `baseUrl` and `drift` are top-level defaults an entry may override. `catalog` is required under `baseUrl: "schemastore"` and optional under a custom host. Every schema's declared `catalog` entry lands in ONE file at `catalogPath` (default `<outputDir>/catalog.json`) — never one file per schema.
-
-Then add two scripts:
-
 ```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
@@ -81,22 +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]
 ```
 
-- Before anything is generated, every advertised frozen version is checked for existence — a schema that advertises a label with nothing on disk fails with `FrozenVersionMissingError` (exit `1`) and nothing is written.
-- `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 the single `catalog.json` every declared catalog entry lands in.
-- `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 file 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 and effective drift tolerance, the single catalog entry's outcome, and `drift: { onDrift, policy? }` — `policy` present only when a flag forced one tolerance over every schema's own); 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. So is a document left behind under an old derived name — an `appendVersion` flip or a `layout` change moved its path, and nothing claims the old file any more: both commands probe the sibling shapes (`<name>.json`, `<name>-<v>.json`, `<v>/<name>.json`, `<v>/<name>-<v>.json`) of every label the config still declares and report each one that exists as an orphaned document, failed by `check`, never deleted by `build`. Nothing else in `outputDir` is looked at, so sharing it with another config, a deploy folder, or the repository root is safe (unless two configs derive the same schema name and version under different layouts into it); a `name` change or a dropped label leaves a file the command cannot know about — delete those by hand.
+- `--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, the `orphaned` document paths when any, `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, a missing frozen version (`FrozenVersionMissingError`), 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 or an output nothing claims (an orphaned catalog file, or an orphaned document at a sibling shape of a derived path) |
+| 2 | config not found, failed to load, or failed `defineConfig` validation |
 | 3 | infrastructure failure |
 | 64 | usage error |
 

package/Report.js

@@ -23,9 +23,11 @@ const catalogLine = (entry) => {
 		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 orphanedLine = (orphan) => `orphaned document ${orphan} (no target, frozen version, or catalog entry claims it — delete it by hand; build never will)`;
 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;
@@ -57,6 +59,7 @@ var Report = class {
 		const lines = [];
 		for (const schema of report.schemas) lines.push(...schemaLines(schema, report));
 		if (report.catalog !== void 0) lines.push(catalogLine(report.catalog));
+		for (const orphan of report.orphaned ?? []) lines.push(orphanedLine(orphan));
 		lines.push(summaryLine(report));
 		return lines;
 	}
@@ -103,6 +106,7 @@ var Report = class {
 				entries: report.catalog.entries,
 				outcome: report.catalog.outcome
 			} } : {},
+			...report.orphaned !== void 0 ? { orphaned: report.orphaned } : {},
 			drifted: report.drifted,
 			gateFailed: report.gateFailed,
 			wrote: report.wrote
@@ -148,6 +152,7 @@ var Report = class {
 			String(report.catalog.entries),
 			report.catalog.outcome
 		]));
+		if (report.orphaned !== void 0) lines.push("", tableRow(["orphaned document", "claimed by"]), tableRow(["---", "---"]), ...report.orphaned.map((orphan) => tableRow([orphan, "nothing — delete by hand"])));
 		lines.push("");
 		if (report.gateFailed) {
 			const failed = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;

package/Runner.js

@@ -1,5 +1,5 @@
-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
 /**
@@ -26,9 +26,61 @@ missing: Schema.Array(Schema.Struct({
 		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 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));
@@ -48,7 +100,11 @@ const parsesEqual = (existing, text) => {
 * 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.
+* 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.
 *
 * **Drift is classified per schema, under that schema's own
 * {@link ResolvedSchema.drift} tolerance — unless `options.policy` is set,
@@ -66,8 +122,26 @@ const parsesEqual = (existing, text) => {
 * **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. The report omits
-* `catalog` entirely when no schema declared one.
+* 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.
+*
+* **A moved path leaves an orphan the derivation cannot see**: an
+* `appendVersion` flip or a `layout` change renames a document's derived
+* path, and the previously written file stays on disk under the old name —
+* for a `published` label, its advertised URL keeps serving a stale
+* document with no report. The derivation has exactly four shapes for a
+* name and label (`<name>.json`, `<name>-<v>.json`, `<v>/<name>.json`,
+* `<v>/<name>-<v>.json`), so both modes probe the sibling shapes of every
+* label the config still knows and report each one that exists as a FILE
+* and that no target, frozen version, or `catalogPath` claims in
+* {@link RunReport.orphaned}. Nothing else on disk is looked at: an
+* `outputDir` shared with another config, a deploy folder, or the
+* repository root holds documents this config cannot tell from its own
+* leftovers, so they are never reported. A `name` change is therefore not
+* caught either — the old name is unknowable. Orphans are reported, never
+* deleted: the CLI may not have written them.
 *
 * @public
 */
@@ -77,15 +151,37 @@ var Runner = class {
 		const fs = yield* FileSystem.FileSystem;
 		const path = yield* Path.Path;
 		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({
+			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
+				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);
@@ -131,7 +227,14 @@ var Runner = class {
 		});
 		const entries = config.schemas.flatMap((schema) => schema.catalog !== void 0 ? [schema.catalog] : []);
 		let catalog;
-		if (entries.length > 0) {
+		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);
@@ -146,6 +249,26 @@ var Runner = class {
 				outcome
 			};
 		}
+		const claimed = /* @__PURE__ */ new Set([path.normalize(config.catalogPath)]);
+		for (const schema of config.schemas) {
+			claimed.add(path.normalize(schema.target.path));
+			for (const frozen of schema.frozen) claimed.add(path.normalize(frozen.path));
+		}
+		const orphaned = [];
+		for (const schema of config.schemas) {
+			const labels = [schema.target.version, ...schema.frozen.map((frozen) => frozen.version)];
+			const shapes = [SchemaVersioning.fileName(schema.name), ...labels.flatMap((version) => version === void 0 ? [] : [
+				SchemaVersioning.fileName(schema.name, version, "flat"),
+				SchemaVersioning.fileName(schema.name, version, "versioned"),
+				SchemaVersioning.fileName(schema.name, version, "versioned", false)
+			])];
+			for (const shape of shapes) {
+				const file = path.normalize(path.join(config.outputDir, shape));
+				if (claimed.has(file)) continue;
+				const info = yield* orNone(fs.stat(file));
+				if (Option.isSome(info) && info.value.type === "File") orphaned.push(file);
+			}
+		}
 		return {
 			mode: options.mode,
 			configPath: options.configPath,
@@ -153,6 +276,7 @@ var Runner = class {
 			...options.policy !== void 0 ? { policy: options.policy } : {},
 			schemas,
 			...catalog !== void 0 ? { catalog } : {},
+			...orphaned.length > 0 ? { orphaned } : {},
 			drifted,
 			gateFailed,
 			wrote: schemas.some((s) => s.outcome === "written") || catalog?.outcome === "written"
@@ -161,4 +285,4 @@ var Runner = class {
 };
 
 //#endregion
-export { FrozenVersionMissingError, Runner };
+export { FrozenVersionIdMismatchError, FrozenVersionMissingError, Runner };

package/cli/commands/check.js

@@ -6,11 +6,14 @@ import { Command } from "effect/unstable/cli";
 /**
 * `schemastore check`: the same walk as `build`, reported and never written.
 * The CI drift gate: it also fails when the committed documents are stale,
-* i.e. whenever `build` would write anything.
+* i.e. whenever `build` would write anything — and on the outputs nothing
+* claims (an orphaned catalog file, or a document left behind at a sibling
+* shape of a derived path), which `build` never deletes: remove them by
+* hand.
 *
 * @public
 */
-const makeCheckCommand = (deps) => Command.make("check", commandFlags, (input) => execute("check", input, deps)).pipe(Command.withDescription("Report what build would do, fail when it would write anything or refuse to, and write nothing"));
+const makeCheckCommand = (deps) => Command.make("check", commandFlags, (input) => execute("check", input, deps)).pipe(Command.withDescription("Report what build would do, fail when it would write anything or refuse to, or when a catalog file or document is orphaned, and write nothing"));
 
 //#endregion
 export { makeCheckCommand };

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({
@@ -45,14 +46,22 @@ var GateError = class extends Schema.TaggedError()("GateError", { count: Schema.
 };
 /**
 * `check` found committed documents that differ from what the config
-* generates (or are missing), so a `build` would write. `check` is the CI
-* drift gate, so a stale tree fails it. Exit `1`.
+* generates (or are missing), so a `build` would write — or outputs
+* nothing claims (an orphaned catalog file, an orphaned document), which
+* `build` never deletes. `check` is the CI drift gate, so a stale tree
+* fails it. Exit `1`. `count` is every finding; `orphaned` the part of it
+* a build cannot clear, so the message names both remedies.
 *
 * @public
 */
-var StaleError = class extends Schema.TaggedError()("StaleError", { count: Schema.Number }) {
+var StaleError = class extends Schema.TaggedError()("StaleError", {
+	count: Schema.Number,
+	orphaned: Schema.optionalKey(Schema.Number)
+}) {
 	get message() {
-		return `${this.count} document(s) are stale; run \`schemastore build\` and commit the result.`;
+		const orphaned = this.orphaned ?? 0;
+		const stale = this.count - orphaned;
+		return [...stale > 0 ? [`${stale} document(s) are stale; run \`schemastore build\` and commit the result.`] : [], ...orphaned > 0 ? [`${orphaned} orphaned output(s) must be deleted by hand; build never will.`] : []].join(" ");
 	}
 };
 /**
@@ -111,7 +120,10 @@ const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
 		mode,
 		configPath: loaded.path,
 		...drift
-	}).pipe(Effect.provide(SchemaFile.layer), Effect.provide(deps.validator ?? SchemaValidator.layer), Effect.catchTag("FrozenVersionMissingError", (error) => Effect.fail(CliRuntime.reported(error, 1))));
+	}).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,8 +140,12 @@ 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?.outcome === "would-write" ? 1 : 0);
-		if (count > 0) return yield* Effect.fail(CliRuntime.reported(new StaleError({ count }), 1));
+		const orphaned = (report.catalog?.outcome === "orphaned" ? 1 : 0) + (report.orphaned?.length ?? 0);
+		const count = report.schemas.filter((schema) => schema.outcome === "would-write").length + (report.catalog?.outcome === "would-write" ? 1 : 0) + orphaned;
+		if (count > 0) return yield* Effect.fail(CliRuntime.reported(new StaleError({
+			count,
+			...orphaned > 0 ? { orphaned } : {}
+		}), 1));
 	}
 });
 

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.11.0"
+		version: "0.13.0"
 	}).pipe(Effect.provide(NodeServices.layer), CliRuntime.reportFailures({
 		exitCode: 3,
 		render

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore-cli",
-	"version": "0.11.0",
+	"version": "0.13.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.11.0",
+		"@effected/schemastore": "0.13.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"
+    }
+  ]
+}