@effected/schemastore-cli 0.18.0 → 0.19.0

package/AjvInstanceValidator.js

@@ -0,0 +1,73 @@
+import { makeAjv } from "./internal/ajv.js";
+import { InstanceFinding, InstanceValidator, InstanceValidatorError } from "@effected/schemastore";
+import { Effect, Layer } from "effect";
+
+//#region src/AjvInstanceValidator.ts
+const findingFromAjvError = (error) => InstanceFinding.make({
+	path: error.instancePath,
+	message: error.message ?? "instance is not valid",
+	keyword: error.keyword
+});
+/**
+* The shipped `InstanceValidator` implementation: the same ajv strict-mode
+* setup `AjvValidator` gates documents with — the declared `KeywordFamilies`
+* keywords and the standard `ajv-formats` vocabulary registered, through the
+* one shared `makeAjv` — pointed at a payload instance instead of the
+* meta-schema.
+*
+* @remarks
+* Lives in the CLI, not the library, for the same reason `AjvValidator`
+* does: `@effected/schemastore` owns the `InstanceValidator` contract and
+* its doubles, an application that imports it at runtime never pulls an
+* engine, and the `schemastore validate` command composes this layer at its
+* edge. It is exported for a program that validates payloads itself and
+* wants the same verdict the command gives — a document the `check` gate
+* admits always compiles here, so the two engines cannot drift.
+*
+* `validate` compiles the document and runs the instance against it. An
+* instance the document rejects answers `InstanceFinding` values — ajv's
+* structured `instancePath` pointer and `keyword` preserved, `allErrors`
+* on, so one run reports every problem, not just the first. A document the
+* engine cannot compile (a meta-schema failure, a strict-mode rejection, a
+* declared keyword whose NAME ajv's grammar refuses) fails
+* `InstanceValidatorError`: unlike `AjvValidator`, whose subject IS the
+* document, this contract's subject is the instance, and a document that
+* yields no verdict is the engine failing to run as a mechanism. The
+* document's own gate is `SchemaValidator`'s job — `schemastore check` runs
+* it before a document is ever published.
+*
+* `strict` defaults to `true` — SchemaStore's gate. Each call builds its own
+* ajv instance, so documents sharing an `$id` never collide.
+*
+* @example
+* ```ts
+* import { InstanceValidator } from "@effected/schemastore";
+* import { AjvInstanceValidator } from "@effected/schemastore-cli";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const validator = yield* InstanceValidator;
+*   return yield* validator.validate({ type: "object" }, { any: "payload" });
+* });
+*
+* Effect.runPromise(Effect.provide(program, AjvInstanceValidator.layer));
+* // => []
+* ```
+*
+* @public
+*/
+var AjvInstanceValidator = class {
+	constructor() {}
+	/** The engine, as an `InstanceValidator` layer. */
+	static layer = Layer.succeed(InstanceValidator, { validate: (document, instance, options) => Effect.try({
+		try: () => {
+			const validate = makeAjv(document, options?.strict ?? true).compile(document);
+			if (validate(instance)) return [];
+			return (validate.errors ?? []).map(findingFromAjvError);
+		},
+		catch: (cause) => InstanceValidatorError.make({ cause })
+	}) });
+};
+
+//#endregion
+export { AjvInstanceValidator };

package/AjvValidator.js

@@ -1,25 +1,8 @@
-import { KeywordFamilies, SchemaValidator, SchemaValidatorError, ValidationFinding } from "@effected/schemastore";
-import { Ajv } from "ajv";
-import ajvFormats from "ajv-formats";
+import { makeAjv } from "./internal/ajv.js";
+import { SchemaValidator, SchemaValidatorError, ValidationFinding } from "@effected/schemastore";
 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",
@@ -47,13 +30,16 @@ const findingFromAjvError = (error) => ValidationFinding.make({
 * carrying a dot or a space. The error channel stays reserved for the engine
 * failing as a mechanism (`SchemaValidatorError`).
 *
+* The ajv setup is `internal/ajv.ts`'s `makeAjv`, shared with
+* `AjvInstanceValidator` so a document this gate admits always compiles in
+* the instance engine too — the two verdicts cannot drift.
+*
 * `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";
@@ -76,15 +62,8 @@ var AjvValidator = class {
 	/** 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 });
+				const ajv = makeAjv(document, options?.strict ?? true);
 				if (!ajv.validateSchema(document)) return (ajv.errors ?? []).map(findingFromAjvError);
 				ajv.compile(document);
 			} catch (cause) {

package/README.md

@@ -5,7 +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 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.
+The `schemastore` command: build and check SchemaStore-shaped JSON Schema documents from a `schemastore.config.ts`, and validate a payload against a published document. 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 engines live: `AjvValidator` (documents) and `AjvInstanceValidator` (payloads), both ajv in strict mode over one shared setup, composed by the commands and exported for a program that drives the pipeline or validates payloads itself, so the library stays free of ajv.
 
 > **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
 > Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
@@ -114,17 +114,19 @@ export default defineConfig({
 ```text
 schemastore build [config] [--drift=strict|semantic|allow] [--on-drift=error|warn] [--force] [--format=human|json]
 schemastore check [config] [--drift=strict|semantic|allow] [--on-drift=error|warn] [--force] [--format=human|json]
+schemastore validate <payload.json> [config] [--schema <path|$id|url>] [--format=human|json]
 ```
 
 - 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 config's catalog slice when any entry declares one, and the merged catalog over every slice.
 - `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 slice left behind after the config's last `catalog` block was removed is reported `orphaned` and fails `check` the same way, but `build` never deletes it — and the merged catalog keeps advertising its entries until it is gone: delete the file by hand, or restore a `catalog` block; a merged `catalog.json` with no slice left is orphaned the same way. 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. A catalog URL advertised by two slices, or a slice that cannot be read or is not a catalog entry array (an undeclared key included), blocks the merged catalog: both commands fail (exit `1`) naming the URL and its slices or the invalid slice, and the merged file is left as it is until the configs or slices are fixed.
+- `validate` answers the question the publication story exists for: does THIS payload conform to the published document it names? The reference is the `--schema` flag or the payload's own `$schema`, resolved file-first and then against every identity a config schema derives (a target `$id`, a frozen version's `$id`/`url`, the catalog `url`) — CI validates an action's output against the committed document with no third-party tool and no network fetch. The payload's `$schema` self-reference is the pointer naming the document: it is stripped before validating only when the resolved document does not declare `$schema` as a root property, since a generated document's `additionalProperties: false` would otherwise reject the very self-reference that names it. A document that does declare `$schema` — the `HostedSchema` pattern above, where the source struct carries `$schema: Schema.Literal(...)` and the generated document requires and const-constrains the key — validates the payload verbatim. A non-conforming payload fails (exit `1`) with one finding per problem, each carrying the JSON pointer into the instance and the keyword; `--format=json` writes one report document to stdout and moves the human lines to stderr.
 - `--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 slice and merged-catalog outcomes, 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 engines, as library exports
 
-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:
+The commands validate 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, through one shared setup both engines use so a document the `check` gate admits always compiles in the instance engine too. The two engine layers are this package's only exports, for a program composing the pipeline or validating payloads directly:
 
 ```ts
 import { SchemaFile, SchemaPipeline } from "@effected/schemastore";
@@ -137,17 +139,28 @@ const AppLayer = Layer.mergeAll(SchemaFile.layer, AjvValidator.layer).pipe(Layer
 const program = SchemaPipeline.run(targets).pipe(Effect.provide(AppLayer));
 ```
 
-Findings come back as values; the error channel carries `SchemaValidatorError` only when the engine fails as a mechanism.
+```ts
+import { InstanceValidator } from "@effected/schemastore";
+import { AjvInstanceValidator } from "@effected/schemastore-cli";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const validator = yield* InstanceValidator;
+  return yield* validator.validate(document, payload);
+}).pipe(Effect.provide(AjvInstanceValidator.layer));
+```
+
+Findings come back as values — `ValidationFinding` pointers into the document for `AjvValidator`, `InstanceFinding` pointers into the payload for `AjvInstanceValidator`; the error channel carries `SchemaValidatorError` / `InstanceValidatorError` only when an engine fails as a mechanism.
 
 ## Exit codes
 
 | code | meaning |
 | ---- | -------------------------------------------------------------------------- |
 | 0 | success, including drift under `onDrift: warn` |
-| 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, a merged catalog blocked by a URL two slices advertise or an invalid slice, or — for `check` — anything `build` would write or an output nothing claims (an orphaned catalog slice or merged catalog, or an orphaned document at a sibling shape of a derived path) |
-| 2 | config not found, failed to load, failed `defineConfig` validation, or a `catalogDir` that is a file or cannot be listed (checked before anything is written) |
-| 3 | infrastructure failure |
-| 64 | usage error |
+| 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, a merged catalog blocked by a URL two slices advertise or an invalid slice, — for `check` — anything `build` would write or an output nothing claims (an orphaned catalog slice or merged catalog, or an orphaned document at a sibling shape of a derived path), or — for `validate` — a payload that does not conform to the resolved document (one finding per problem, pointer and keyword each) |
+| 2 | config not found, failed to load, failed `defineConfig` validation, a `catalogDir` that is a file or cannot be listed (checked before anything is written), or — for `validate` — a payload that cannot be read or parsed, or a `--schema`/`$schema` reference that is neither an existing file nor an identity any config schema derives, or names a document that cannot be read or parsed |
+| 3 | infrastructure failure (for `validate`, an engine mechanism failure — a document the instance engine cannot compile — included) |
+| 64 | usage error (for `validate`, a payload with no `$schema` and no `--schema` given, included) |
 
 ## License
 

package/cli/commands/validate.js

@@ -0,0 +1,257 @@
+import { AjvInstanceValidator } from "../../AjvInstanceValidator.js";
+import { ConfigLoader } from "../../ConfigLoader.js";
+import { configArgument, formatFlag } from "../flags.js";
+import { InstanceValidator } from "@effected/schemastore";
+import { Console, Effect, FileSystem, JsonPointer, Option, Path, Predicate, Schema } from "effect";
+import { CliRuntime } from "@effected/cli";
+import { Argument, Command, Flag } from "effect/cli";
+
+//#region src/cli/commands/validate.ts
+/**
+* The payload file could not be read or parsed: it does not exist, the
+* filesystem refused it, or its contents are not JSON. Nothing was
+* validated. Exit `2`.
+*
+* @public
+*/
+var PayloadError = class extends Schema.TaggedError()("PayloadError", {
+	path: Schema.String,
+	reason: Schema.String
+}) {
+	get message() {
+		return `Failed to read payload ${this.path}: ${this.reason}`;
+	}
+};
+/**
+* The payload names no schema and `--schema` was not given, so there is
+* nothing to validate against. A usage error — the remedy is in how the
+* command is invoked. Exit `64`.
+*
+* @public
+*/
+var MissingSchemaRefError = class extends Schema.TaggedError()("MissingSchemaRefError", { path: Schema.String }) {
+	get message() {
+		return `Payload ${this.path} has no "$schema" property; pass --schema <path|$id> to name the document to validate against.`;
+	}
+};
+/**
+* The schema reference — `--schema` or the payload's `$schema` — resolved to
+* no readable document: it is neither an existing file nor an identity any
+* config schema derives (`$id`, a frozen `$id`/`url`, a catalog `url`), or
+* the document it names could not be read or parsed. Exit `2`.
+*
+* @public
+*/
+var SchemaResolutionError = class extends Schema.TaggedError()("SchemaResolutionError", {
+	$ref: Schema.String,
+	reason: Schema.String
+}) {
+	get message() {
+		return `Failed to resolve schema "${this.$ref}": ${this.reason}`;
+	}
+};
+/**
+* The payload does not conform to the resolved document: the engine
+* answered findings, each already reported. Exit `1` — a validation
+* verdict, the reason CI runs the command.
+*
+* @public
+*/
+var ValidationFailedError = class extends Schema.TaggedError()("ValidationFailedError", {
+	count: Schema.Number,
+	payload: Schema.String,
+	schema: Schema.String
+}) {
+	get message() {
+		return `${this.count} finding(s): ${this.payload} does not conform to ${this.schema}`;
+	}
+};
+var ReadJsonError = class extends Schema.TaggedError()("ReadJsonError", {
+	path: Schema.String,
+	reason: Schema.String
+}) {};
+const readJson = Effect.fn("schemastore.validate.readJson")(function* (file) {
+	const text = yield* (yield* FileSystem.FileSystem).readFileString(file).pipe(Effect.mapError((cause) => new ReadJsonError({
+		path: file,
+		reason: cause.message
+	})));
+	return yield* Effect.try({
+		try: () => JSON.parse(text),
+		catch: (cause) => new ReadJsonError({
+			path: file,
+			reason: cause instanceof Error ? cause.message : String(cause)
+		})
+	});
+});
+const identityMap = (config) => {
+	const identities = /* @__PURE__ */ new Map();
+	const add = (identity, name, path) => {
+		if (identity !== void 0 && !identities.has(identity)) identities.set(identity, {
+			name,
+			path
+		});
+	};
+	for (const schema of config.schemas) {
+		add(schema.target.$id, schema.name, schema.target.path);
+		for (const frozen of schema.frozen) {
+			add(frozen.$id, schema.name, frozen.path);
+			add(frozen.url, schema.name, frozen.path);
+		}
+		add(schema.catalog?.url, schema.name, schema.target.path);
+	}
+	return identities;
+};
+const resolveDocument = Effect.fn("schemastore.validate.resolveDocument")(function* ($ref, input, deps) {
+	const path = yield* Path.Path;
+	const fs = yield* FileSystem.FileSystem;
+	const unresolved = (reason) => Effect.fail(CliRuntime.reported(new SchemaResolutionError({
+		$ref,
+		reason
+	}), 2));
+	const candidate = path.resolve(deps.cwd, $ref);
+	if (yield* fs.exists(candidate).pipe(Effect.orElseSucceed(() => false))) return {
+		parsed: yield* readJson(candidate).pipe(Effect.catchTag("ReadJsonError", ({ reason }) => unresolved(reason))),
+		source: candidate
+	};
+	const loaded = yield* ConfigLoader.load({
+		cwd: deps.cwd,
+		...Option.isSome(input.config) ? { explicit: input.config.value } : {},
+		...deps.importModule !== void 0 ? { importModule: deps.importModule } : {}
+	});
+	const match = identityMap(loaded.config).get($ref);
+	if (match === void 0) return yield* unresolved("not an existing file, and no schema in the config derives this $id or url");
+	return {
+		parsed: yield* readJson(match.path).pipe(Effect.catchTag("ReadJsonError", ({ reason }) => unresolved(`schema "${match.name}" resolves to ${match.path}, which ${reason}`))),
+		source: match.path
+	};
+});
+const findingLine = (finding) => `  ${finding.path === "" ? "(root)" : finding.path}: ${finding.message}${finding.keyword !== void 0 ? ` [${finding.keyword}]` : ""}`;
+const jsonReport = (payload, $ref, source, findings) => JSON.stringify({
+	payload,
+	schema: $ref,
+	document: source,
+	valid: findings.length === 0,
+	findings: findings.map((finding) => ({
+		path: finding.path,
+		message: finding.message,
+		...finding.keyword !== void 0 ? { keyword: finding.keyword } : {}
+	}))
+});
+const schemaPropertyOf = (payload) => Predicate.isObject(payload) && !Array.isArray(payload) && typeof payload.$schema === "string" ? payload.$schema : void 0;
+const defsTarget = (document, ref) => {
+	if (!ref.startsWith("#/")) return;
+	let name;
+	try {
+		const tokens = ref.slice(2).split("/").map((token) => JsonPointer.unescapeToken(decodeURIComponent(token)));
+		if (tokens.length !== 2 || tokens[0] !== "$defs") return;
+		name = tokens[1];
+	} catch {
+		return;
+	}
+	const defs = document.$defs;
+	if (!Predicate.isObject(defs) || Array.isArray(defs) || !Object.hasOwn(defs, name)) return;
+	const entry = defs[name];
+	return Predicate.isObject(entry) && !Array.isArray(entry) ? entry : void 0;
+};
+const declaresSchemaProperty = (document) => {
+	const declares = (node) => {
+		const properties = node.properties;
+		return Predicate.isObject(properties) && !Array.isArray(properties) && "$schema" in properties;
+	};
+	const seen = /* @__PURE__ */ new Set();
+	const queue = [document];
+	for (let node = queue.shift(); node !== void 0; node = queue.shift()) {
+		if (declares(node)) return true;
+		if (typeof node.$ref === "string" && !seen.has(node.$ref)) {
+			seen.add(node.$ref);
+			const target = defsTarget(document, node.$ref);
+			if (target !== void 0) queue.push(target);
+		}
+		if (Array.isArray(node.allOf)) {
+			for (const member of node.allOf) if (Predicate.isObject(member) && !Array.isArray(member)) queue.push(member);
+		}
+	}
+	return false;
+};
+const withoutSchemaRef = (payload, document) => {
+	if (schemaPropertyOf(payload) === void 0 || declaresSchemaProperty(document)) return payload;
+	const rest = { ...payload };
+	delete rest.$schema;
+	return rest;
+};
+/**
+* Run one `schemastore validate`.
+*
+* @remarks
+* Reads the payload, resolves the schema reference (`--schema`, else the
+* payload's `$schema`) file-first then against the config's derived
+* identities, validates with `deps.instanceValidator` or the real engine,
+* and reports. A top-level string `$schema` on the payload is the pointer
+* naming the document: it is stripped from the instance before validating
+* only when the resolved document does not declare `$schema` as a root
+* property; a document that does declare it (the HostedSchema pattern,
+* where the key is required and const-constrained) sees the payload
+* verbatim, and the rest of the payload always goes verbatim. Findings fail
+* `ValidationFailedError` at exit `1`; a
+* payload that cannot be read or parsed is `PayloadError` at `2`, an
+* unresolvable reference `SchemaResolutionError` at `2`, a payload naming
+* nothing `MissingSchemaRefError` at `64`, and an engine mechanism failure
+* (`InstanceValidatorError`) flows unmarked to the runtime's exit `3`.
+* `--format json` writes one report document to stdout and moves the human
+* lines to stderr, exactly as `build`/`check` do.
+*
+* @public
+*/
+const runValidate = Effect.fn("schemastore.validate")(function* (input, deps) {
+	const payloadPath = (yield* Path.Path).resolve(deps.cwd, input.payload);
+	const payload = yield* readJson(payloadPath).pipe(Effect.catchTag("ReadJsonError", ({ reason }) => Effect.fail(CliRuntime.reported(new PayloadError({
+		path: payloadPath,
+		reason
+	}), 2))));
+	const $ref = Option.getOrUndefined(input.schema) ?? schemaPropertyOf(payload);
+	if ($ref === void 0) return yield* Effect.fail(CliRuntime.reported(new MissingSchemaRefError({ path: payloadPath }), 64));
+	const resolved = yield* resolveDocument($ref, input, deps);
+	const document = resolved.parsed;
+	if (!Predicate.isObject(document) || Array.isArray(document)) return yield* Effect.fail(CliRuntime.reported(new SchemaResolutionError({
+		$ref,
+		reason: `${resolved.source} is not a JSON object`
+	}), 2));
+	const findings = yield* Effect.gen(function* () {
+		return yield* (yield* InstanceValidator).validate(document, withoutSchemaRef(payload, document));
+	}).pipe(Effect.provide(deps.instanceValidator ?? AjvInstanceValidator.layer));
+	const human = findings.length === 0 ? [`valid ${payloadPath} against ${resolved.source}`] : [...findings.map(findingLine), `${findings.length} finding(s): ${payloadPath} does not conform to ${$ref}`];
+	if (input.format === "json") {
+		yield* Console.log(jsonReport(payloadPath, $ref, resolved.source, findings));
+		for (const line of human) yield* Effect.logInfo(line);
+	} else for (const line of human) yield* Console.log(line);
+	if (findings.length > 0) return yield* Effect.fail(CliRuntime.reported(new ValidationFailedError({
+		count: findings.length,
+		payload: payloadPath,
+		schema: $ref
+	}), 1));
+});
+/**
+* `schemastore validate`: check a payload against a published schema
+* document. The reference (`--schema`, else the payload's `$schema`) is an
+* existing file path or an identity the config derives — a schema's `$id`,
+* a frozen version's `$id`/`url`, or a catalog `url` — so CI validates an
+* action's output against the committed document without a third-party
+* tool or a network fetch. A top-level string `$schema` on the payload is
+* consumed as that pointer; it is stripped before validating only when the
+* resolved document does not declare `$schema` as a root property, since a
+* generated document's `additionalProperties: false` would otherwise
+* reject the very self-reference that names it. A document that declares
+* `$schema` — the HostedSchema pattern — validates the payload verbatim
+* and enforces its own const constraint on the key.
+*
+* @public
+*/
+const makeValidateCommand = (deps) => Command.make("validate", {
+	payload: Argument.String("payload").pipe(Argument.withDescription("Path to the JSON payload to validate")),
+	schema: Flag.String("schema").pipe(Flag.optional, Flag.withDescription("The document to validate against: a file path, or a $id/url a config schema derives; omitted, the payload's own $schema property")),
+	config: configArgument,
+	format: formatFlag
+}, (input) => runValidate(input, deps)).pipe(Command.withDescription("Validate a JSON payload against a published schema document, resolved by path or by the config's derived $id/url identities"));
+
+//#endregion
+export { MissingSchemaRefError, PayloadError, SchemaResolutionError, ValidationFailedError, makeValidateCommand, runValidate };

package/cli/root.js

@@ -1,5 +1,6 @@
 import { makeBuildCommand } from "./commands/build.js";
 import { makeCheckCommand } from "./commands/check.js";
+import { makeValidateCommand } from "./commands/validate.js";
 import { Command } from "effect/cli";
 
 //#region src/cli/root.ts
@@ -12,10 +13,16 @@ import { Command } from "effect/cli";
 const makeCommands = (deps) => {
 	const build = makeBuildCommand(deps);
 	const check = makeCheckCommand(deps);
+	const validate = makeValidateCommand(deps);
 	return {
-		root: Command.make("schemastore", {}).pipe(Command.withDescription("Build and check SchemaStore-shaped JSON Schema documents from a schemastore.config.ts"), Command.withSubcommands([build, check])),
+		root: Command.make("schemastore", {}).pipe(Command.withDescription("Build and check SchemaStore-shaped JSON Schema documents from a schemastore.config.ts, and validate payloads against them"), Command.withSubcommands([
+			build,
+			check,
+			validate
+		])),
 		build,
-		check
+		check,
+		validate
 	};
 };
 

package/index.d.ts

@@ -1,5 +1,60 @@
-import { SchemaValidator } from "@effected/schemastore";
+import { InstanceValidator, SchemaValidator } from "@effected/schemastore";
 import { Layer } from "effect";
+//#region src/AjvInstanceValidator.d.ts
+/**
+ * The shipped `InstanceValidator` implementation: the same ajv strict-mode
+ * setup `AjvValidator` gates documents with — the declared `KeywordFamilies`
+ * keywords and the standard `ajv-formats` vocabulary registered, through the
+ * one shared `makeAjv` — pointed at a payload instance instead of the
+ * meta-schema.
+ *
+ * @remarks
+ * Lives in the CLI, not the library, for the same reason `AjvValidator`
+ * does: `@effected/schemastore` owns the `InstanceValidator` contract and
+ * its doubles, an application that imports it at runtime never pulls an
+ * engine, and the `schemastore validate` command composes this layer at its
+ * edge. It is exported for a program that validates payloads itself and
+ * wants the same verdict the command gives — a document the `check` gate
+ * admits always compiles here, so the two engines cannot drift.
+ *
+ * `validate` compiles the document and runs the instance against it. An
+ * instance the document rejects answers `InstanceFinding` values — ajv's
+ * structured `instancePath` pointer and `keyword` preserved, `allErrors`
+ * on, so one run reports every problem, not just the first. A document the
+ * engine cannot compile (a meta-schema failure, a strict-mode rejection, a
+ * declared keyword whose NAME ajv's grammar refuses) fails
+ * `InstanceValidatorError`: unlike `AjvValidator`, whose subject IS the
+ * document, this contract's subject is the instance, and a document that
+ * yields no verdict is the engine failing to run as a mechanism. The
+ * document's own gate is `SchemaValidator`'s job — `schemastore check` runs
+ * it before a document is ever published.
+ *
+ * `strict` defaults to `true` — SchemaStore's gate. Each call builds its own
+ * ajv instance, so documents sharing an `$id` never collide.
+ *
+ * @example
+ * ```ts
+ * import { InstanceValidator } from "@effected/schemastore";
+ * import { AjvInstanceValidator } from "@effected/schemastore-cli";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const validator = yield* InstanceValidator;
+ *   return yield* validator.validate({ type: "object" }, { any: "payload" });
+ * });
+ *
+ * Effect.runPromise(Effect.provide(program, AjvInstanceValidator.layer));
+ * // => []
+ * ```
+ *
+ * @public
+ */
+export declare class AjvInstanceValidator {
+  private constructor();
+  /** The engine, as an `InstanceValidator` layer. */
+  static readonly layer: Layer.Layer<InstanceValidator>;
+}
+//#endregion
 //#region src/AjvValidator.d.ts
 /**
  * The shipped `SchemaValidator` implementation: ajv strict mode over the
@@ -23,13 +78,16 @@ import { Layer } from "effect";
  * carrying a dot or a space. The error channel stays reserved for the engine
  * failing as a mechanism (`SchemaValidatorError`).
  *
+ * The ajv setup is `internal/ajv.ts`'s `makeAjv`, shared with
+ * `AjvInstanceValidator` so a document this gate admits always compiles in
+ * the instance engine too — the two verdicts cannot drift.
+ *
  * `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";

package/index.js

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

package/internal/ajv.js

@@ -0,0 +1,51 @@
+import { KeywordFamilies } from "@effected/schemastore";
+import { Ajv } from "ajv";
+import ajvFormats from "ajv-formats";
+
+//#region src/internal/ajv.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);
+	}
+};
+/**
+* Build the shared strict-mode ajv instance over a document: the standard
+* `ajv-formats` vocabulary registered (`keywords: false` is load-bearing —
+* the plugin's default ALSO registers `formatMaximum` / `formatMinimum` and
+* their exclusive variants, which `DocumentLint` answers as unknown
+* keywords, and registering them would drift the two verdicts apart), plus
+* every declared `KeywordFamilies` keyword the document carries.
+*
+* THROWS when ajv itself refuses the setup — most often a declared keyword
+* whose NAME ajv's own grammar (`/^[a-z_$][a-z0-9_$:-]*$/i`) rejects, such
+* as an `x-ai-*` key carrying a dot or a space. Each caller decides what
+* that throw means for its subject: a finding for `AjvValidator` (the
+* document IS the subject there), an engine failure for
+* `AjvInstanceValidator` (there the subject is the instance, and a document
+* that will not compile yields no verdict about it).
+*/
+const makeAjv = (document, strict) => {
+	const ajv = new Ajv({
+		strict,
+		allErrors: true
+	});
+	addFormats(ajv, { keywords: false });
+	const declared = /* @__PURE__ */ new Set();
+	collectDeclaredKeywords(document, declared, 0);
+	for (const keyword of declared) ajv.addKeyword({ keyword });
+	return ajv;
+};
+
+//#endregion
+export { makeAjv };

package/main.js

@@ -10,7 +10,7 @@ const render = (error) => CliError.isCliError(error) && error._tag === "ShowHelp
 const main = () => {
 	const run = program(process.argv.slice(2), {
 		cwd: process.cwd(),
-		version: "0.18.0"
+		version: "0.19.0"
 	}).pipe(Effect.provide(NodeServices.layer), CliRuntime.reportFailures({
 		exitCode: 3,
 		render

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore-cli",
-	"version": "0.18.0",
+	"version": "0.19.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": [
@@ -50,7 +50,7 @@
 		"jiti": "^2.6.0"
 	},
 	"peerDependencies": {
-		"@effected/schemastore": "0.18.0",
+		"@effected/schemastore": "0.19.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {