@effected/schemastore 0.1.1 → 0.2.0

package/DocumentDiff.js

@@ -0,0 +1,178 @@
+import { KeywordFamilies } from "./KeywordFamilies.js";
+
+//#region src/DocumentDiff.ts
+const DOCUMENTATION_KEYWORDS = /* @__PURE__ */ new Set([
+	"title",
+	"description",
+	"$comment"
+]);
+const SCHEMA_MAP_KEYWORDS = /* @__PURE__ */ new Set([
+	"properties",
+	"patternProperties",
+	"$defs",
+	"definitions"
+]);
+const SCHEMA_ARRAY_KEYWORDS = /* @__PURE__ */ new Set([
+	"allOf",
+	"anyOf",
+	"oneOf"
+]);
+const SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
+	"additionalItems",
+	"additionalProperties",
+	"propertyNames",
+	"contains",
+	"if",
+	"then",
+	"else",
+	"not"
+]);
+const isSchemaObject = (node) => typeof node === "object" && node !== null && !Array.isArray(node);
+const VALUE_COMPARISON_STACK_GUARD = 256 * 8;
+const deepEqual = (a, b, depth) => {
+	if (a === b) return true;
+	if (depth >= VALUE_COMPARISON_STACK_GUARD) return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((element, index) => deepEqual(element, b[index], depth + 1));
+	}
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return false;
+	const aKeys = Object.keys(a);
+	if (aKeys.length !== Object.keys(b).length) return false;
+	return aKeys.every((key) => Object.hasOwn(b, key) && deepEqual(a[key], b[key], depth + 1));
+};
+const worst = (left, right) => {
+	if (left === "contract" || right === "contract") return "contract";
+	if (left === "annotations" || right === "annotations") return "annotations";
+	return "none";
+};
+const isAnnotationKey = (key) => DOCUMENTATION_KEYWORDS.has(key) || KeywordFamilies.isDeclared(key);
+const compareSchema = (a, b, depth) => {
+	if (a === b) return "none";
+	if (depth >= 256) return deepEqual(a, b, 0) ? "none" : "contract";
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return deepEqual(a, b, depth) ? "none" : "contract";
+	let change = "none";
+	const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const key of keys) {
+		if (!(Object.hasOwn(a, key) && Object.hasOwn(b, key))) {
+			change = worst(change, isAnnotationKey(key) ? "annotations" : "contract");
+			if (change === "contract") return "contract";
+			continue;
+		}
+		const left = a[key];
+		const right = b[key];
+		if (isAnnotationKey(key)) {
+			change = worst(change, deepEqual(left, right, depth) ? "none" : "annotations");
+			continue;
+		}
+		if (SCHEMA_MAP_KEYWORDS.has(key)) change = worst(change, compareSchemaMap(left, right, depth + 1));
+		else if (SCHEMA_ARRAY_KEYWORDS.has(key)) change = worst(change, compareSchemaArray(left, right, depth + 1));
+		else if (SCHEMA_KEYWORDS.has(key)) change = worst(change, compareSchema(left, right, depth + 1));
+		else if (key === "items") change = worst(change, Array.isArray(left) || Array.isArray(right) ? compareSchemaArray(left, right, depth + 1) : compareSchema(left, right, depth + 1));
+		else if (key === "dependencies") change = worst(change, compareDependencies(left, right, depth + 1));
+		else change = worst(change, deepEqual(left, right, depth) ? "none" : "contract");
+		if (change === "contract") return "contract";
+	}
+	return change;
+};
+const compareSchemaMap = (a, b, depth) => {
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return deepEqual(a, b, depth) ? "none" : "contract";
+	let change = "none";
+	const names = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const name of names) {
+		if (!Object.hasOwn(a, name) || !Object.hasOwn(b, name)) return "contract";
+		change = worst(change, compareSchema(a[name], b[name], depth + 1));
+		if (change === "contract") return "contract";
+	}
+	return change;
+};
+const compareSchemaArray = (a, b, depth) => {
+	if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return "contract";
+	let change = "none";
+	for (const [index, element] of a.entries()) {
+		change = worst(change, compareSchema(element, b[index], depth + 1));
+		if (change === "contract") return "contract";
+	}
+	return change;
+};
+const compareDependencies = (a, b, depth) => {
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return deepEqual(a, b, depth) ? "none" : "contract";
+	let change = "none";
+	const names = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const name of names) {
+		if (!Object.hasOwn(a, name) || !Object.hasOwn(b, name)) return "contract";
+		const left = a[name];
+		const right = b[name];
+		change = worst(change, Array.isArray(left) || Array.isArray(right) ? deepEqual(left, right, depth) ? "none" : "contract" : compareSchema(left, right, depth + 1));
+		if (change === "contract") return "contract";
+	}
+	return change;
+};
+/**
+* Classifies the difference between two emitted schema documents by
+* meaning: identical, documentation-only, or a change to the validation
+* contract.
+*
+* The walk is keyword-position aware in exactly the way {@link DocumentLint}'s
+* is — a property NAMED `description` inside `properties` is data, not an
+* annotation — and object key order is never a difference, so a document
+* reformatted (or key-sorted) by another tool still classifies as `"none"`.
+*
+* Total: hostile nesting past the package's depth cap stops the structural
+* walk and degrades to a whole-subtree comparison reported as `"contract"`
+* when unequal, never a throw.
+*
+* @example
+* ```ts
+* import { DocumentDiff } from "@effected/schemastore";
+*
+* const before = { type: "object", properties: { name: { type: "string", description: "A" } } };
+* const after = { type: "object", properties: { name: { type: "string", description: "B" } } };
+*
+* console.log(DocumentDiff.classify(before, after));
+* // => "annotations"  (republish transparently; no new version needed)
+*
+* console.log(DocumentDiff.classify(before, { ...before, required: ["name"] }));
+* // => "contract"     (documents valid before may be invalid now)
+* ```
+*
+* @public
+*/
+var DocumentDiff = class {
+	constructor() {}
+	/**
+	* Classify the difference between two emitted document values (the
+	* `toJson()` publication shape, or anything parsed from a written
+	* schema file). Both sides are plain JSON values, so this compares an
+	* on-disk document against a freshly built one without either being a
+	* {@link StoreDocument}.
+	*/
+	static classify(existing, next) {
+		return compareSchema(existing, next, 0);
+	}
+	/**
+	* Whether a classification means "nothing changed" — `true` only for
+	* `"none"`.
+	*
+	* Exists so the clean case is not a string literal every consumer
+	* spells for itself. `"created"` is deliberately NOT clean: a file that
+	* did not exist is a change.
+	*/
+	static isClean(change) {
+		return change === "none";
+	}
+	/**
+	* Whether `key`, standing at a schema position, is a documentation
+	* keyword: `title`, `description`, `$comment`, or any declared
+	* non-standard language-server family ({@link KeywordFamilies}).
+	*
+	* `default`, `examples`, `readOnly` and `writeOnly` are deliberately
+	* NOT documentation — consumers act on them.
+	*/
+	static isAnnotationKeyword(key) {
+		return isAnnotationKey(key);
+	}
+};
+
+//#endregion
+export { DocumentDiff };

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/)
 
-Build, version and lint SchemaStore-shaped Draft-07 JSON Schema documents from Effect Schema sources. Core effect already owns the generation pipeline — `Schema.toJsonSchemaDocument` produces Draft 2020-12 and `JsonSchema.toDocumentDraft07` lowers it — and this package owns what [SchemaStore](https://www.schemastore.org) expects around that output: the publication shape (`$schema` + `$id` + root + `$defs`, with the `#/definitions` → `#/$defs` ref rewrite the lowering makes necessary), annotation carriers that keep the language-server keyword families alive through the lowering, catalog entries in both versioning modes, structural and hygiene lints, canonical JSON text, write-if-changed file IO and a validation contract seam a consumer closes with a real engine at the edge.
+Build, version, validate and lint SchemaStore-shaped Draft-07 JSON Schema documents from Effect Schema sources. Core effect already owns the generation pipeline: `Schema.toJsonSchemaDocument` produces Draft 2020-12 and `JsonSchema.toDocumentDraft07` lowers it. This package owns what [SchemaStore](https://www.schemastore.org) expects around that output — the publication shape (`$schema` + `$id` + root + `$defs`, with the `#/definitions` → `#/$defs` ref rewrite the lowering makes necessary), annotation carriers that keep the language-server keyword families alive through the lowering, catalog entries in both versioning modes, structural and hygiene lints, ajv strict-mode validation, canonical JSON text and content-comparing write-if-changed file IO. `SchemaPipeline` runs that whole emit loop over a list of targets, so a build script calls one function.
 
 > **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
 > development against a single pinned Effect v4 beta. Packages graduate to
@@ -23,7 +23,7 @@ Build, version and lint SchemaStore-shaped Draft-07 JSON Schema documents from E
 
 Generating a JSON Schema from an Effect Schema is a solved problem — core does it. Publishing that schema where editors find it is not. SchemaStore recommends Draft-07 because that is what the language servers actually support, and core's Draft-07 lowering has two consequences a publisher must deal with: it rewrites `$ref` pointers to the canonical `#/definitions/...` form while the published document keeps its pool under `$defs`, and it drops every keyword outside its fixed copy-list — which is exactly where `markdownDescription`, `x-taplo` and the other editor keywords live. Around the document itself sits SchemaStore's own contract: ajv strict mode as the validation gate, catalog entries whose `fileMatch` patterns must not be generic and versioned schemas as suffixed files plus a `versions` map whose `url` points at the latest. This package is that last mile, so a build script does not have to reinvent it.
 
-The scope is deliberately narrow. There is no schema construction here, no ref resolution beyond the document's own `$defs` pool, no dialect conversion and no JSON Schema engine anywhere in the runtime graph — core's `JsonSchema` owns the pipeline, ajv stays at the consumer's edge behind a contract, and this package owns the SchemaStore shape in between.
+The scope is deliberately narrow. There is no schema construction here, no ref resolution beyond the document's own `$defs` pool and no dialect conversion — core's `JsonSchema` owns the generation pipeline, ajv provides the validation gate and this package owns the SchemaStore shape in between.
 
 ## Install
 
@@ -39,7 +39,7 @@ Requires Node.js >=24.11.0.
 
 All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
 
-`effect` v4 is the only peer dependency. `@effected/semver` rides along as a regular dependency — it does the version ordering inside `SchemaVersioning`, and no `SemVer` type surfaces in the public API. Every module is pure except `SchemaFile`, whose layer requires core `FileSystem` and `Path`, supplied at the edge from `@effect/platform-node` or `@effect/platform-bun`.
+`effect` v4 is the only peer dependency. Two regular dependencies ride along: `@effected/semver` does the version ordering inside `SchemaVersioning`, with no `SemVer` type surfacing in the public API, and `ajv` is the engine behind `SchemaValidator.layer`. ajv therefore arrives with this package and the validation examples below need no extra install; if your own code imports ajv directly, depend on it directly rather than relying on this one's copy. Every module is pure except `SchemaFile`, whose layer requires core `FileSystem` and `Path`, supplied at the edge from `@effect/platform-node` or `@effect/platform-bun`.
 
 ## Quick start
 
@@ -77,12 +77,9 @@ console.log(Effect.runSync(program));
 
 `fromSchema` runs the whole pipeline — 2020-12 generation, Draft-07 lowering, the `$ref` rewrite and the annotation re-graft — so every `$ref` in a built document already resolves against its `$defs` pool. `toJson()` is the flat publication shape (`$defs` omitted when empty) and `serializeResult` routes through the owned canonical serializer, tab-indented with a single trailing newline. If core cannot convert a schema, the failure is typed as `SchemaConversionError` and carries the `$id` and the structured cause.
 
-## Two rules to read first
+## Annotate at the definition site
 
-Two constraints bite consumers who do not know them, so they come before the feature tour:
-
-- **Annotate at the definition site.** An annotation applied at a hoisted schema's *usage* site — `Person.annotate({ ... })` inside a struct field — reaches neither the `$ref` node nor the `$defs` pool entry, even before the Draft-07 lowering. It silently carries nothing. Put the annotation where the schema is defined.
-- **Read version ordering from labels, never from key position.** A versioned catalog's `versions` map is a JSON object, and JavaScript enumerates integer-like keys first: a bare-major label like `"2"` serializes ahead of every dotted label regardless of insertion order. `SchemaVersioning.Order` and `SchemaVersioning.latest` order by the labels themselves; key position promises nothing.
+One constraint bites consumers who do not know it, so it comes before the feature tour. An annotation applied at a hoisted schema's *usage* site (`Person.annotate({ ... })` inside a struct field) reaches neither the `$ref` node nor the `$defs` pool entry, even before the Draft-07 lowering. It silently carries nothing. Put the annotation where the schema is defined.
 
 ## Carrying language-server annotations
 
@@ -111,7 +108,7 @@ The declared families are always admitted — `KeywordFamilies` is the one regis
 
 ## Catalog entries and versioning
 
-`CatalogEntry` is the `catalog.json` entry as a `Schema.Class`, so decoding an existing entry and encoding one for submission are the same artifact. `SchemaVersion` is SchemaStore's own label grammar — `major[.minor[.patch]][-prerelease]`, leading zeros rejected — not strict SemVer: `1.2` is a valid catalog label that a SemVer parser rejects. Ordering pads labels to full SemVer internally, so `1.10` sorts above `1.9` numerically and the label round-trips verbatim.
+`CatalogEntry` is the `catalog.json` entry as a `Schema.Class`, so decoding an existing entry and encoding one for submission are the same artifact. `SchemaVersion` is a **full three-component SemVer** label — `major.minor.patch` with an optional prerelease, enforced by `@effected/semver` — so ordering is plain SemVer precedence (`1.10.0` above `1.9.0`) and the label round-trips verbatim. Build metadata is rejected (`1.0.0+build.5` does not parse): SemVer precedence ignores it, so two labels differing only in build would compare equal and both claim to be the latest. Surrounding whitespace is rejected for the same round-tripping reason. The file-name convention is SchemaStore's own `<name>-<version>.json`; the label grammar is the one deliberate divergence, since the store's corpus uses partial labels like `1.2` that no SemVer parser accepts and that cannot be split back out of a file name unambiguously.
 
 `CatalogEntry.assemble` derives both catalog modes from the same inputs. Pass `versions` for the versioned mode — the `versions` map carries every label and `url` points at the latest version's file — or omit it for the unversioned single-file mode. An empty `versions` array is a contradiction and throws; pass `undefined` instead.
 
@@ -120,7 +117,7 @@ import { CatalogEntry, SchemaVersioning } from "@effected/schemastore";
 import { Effect } from "effect";
 
 const program = Effect.gen(function* () {
-  const versions = yield* Effect.forEach(["1.9", "1.10"], SchemaVersioning.parse);
+  const versions = yield* Effect.forEach(["1.9.0", "1.10.0"], SchemaVersioning.parse);
   return CatalogEntry.assemble({
     name: "My Tool",
     description: "Configuration for My Tool.",
@@ -132,7 +129,7 @@ const program = Effect.gen(function* () {
 });
 
 console.log(Effect.runSync(program).url);
-// => "https://example.com/schemas/mytool-1.10.json"
+// => "https://example.com/schemas/mytool-1.10.0.json"
 ```
 
 The `fileMatch` hygiene lint enforces the patterns SchemaStore's reviewers enforce, as pure shape analysis — it never matches a pattern against a path, so there is no glob engine behind it:
@@ -163,25 +160,13 @@ The keyword walk is position-aware: a *property* named `unevaluatedProperties` i
 
 ## Real-engine validation
 
-SchemaStore's own gate is ajv strict mode, and `SchemaValidator` is the seam that reaches it without ajv ever entering this package's dependency graph. The contract's channel convention: findings are values — an ajv strict-mode compile failure is a report, not an error — and the error channel is reserved for the engine failing as a mechanism (`SchemaValidatorError`). The package ships `noop` (validates nothing) and `makeTest` / `layerTest` (unstubbed members die naming themselves); the consumer closes the seam at the application edge. The `ajv` import below (like `@effect/platform-node` in the file-writing example) is the consumer's own dependency — install it to run the example; nothing here depends on it:
+SchemaStore's own gate is ajv strict mode, and this package ships it. `SchemaValidator.layer` is a real ajv implementation: provide it and validation works, with no adapter to write. ajv is a direct dependency because SchemaStore's gate *is* ajv, and this package is build-time tooling for emitting documents that clear that gate. Keeping the engine out of the graph bought nothing and left every consumer writing the same adapter.
 
-```ts
-import { SchemaValidator, StoreDocument, ValidationFinding } from "@effected/schemastore";
-import Ajv from "ajv";
-import { Effect, Layer, Schema } from "effect";
+The channel convention holds: findings are values — a strict-mode rejection is a report, not an error — and the error channel is reserved for the engine failing as a mechanism (`SchemaValidatorError`). Meta-schema failures keep ajv's structured `instancePath` and `keyword`; a strict-mode rejection, which ajv raises by throwing, becomes a root-pathed finding. The declared language-server keyword families are registered before compiling, so ajv does not reject what `DocumentLint` deliberately allows — one `KeywordFamilies` predicate governs both verdicts.
 
-const AjvValidator = Layer.succeed(SchemaValidator, {
-  validate: (document, options) =>
-    Effect.sync(() => {
-      const ajv = new Ajv({ strict: options?.strict !== false, allErrors: true });
-      try {
-        ajv.compile(document);
-        return [];
-      } catch (error) {
-        return [ValidationFinding.make({ path: "", message: String(error) })];
-      }
-    }),
-});
+```ts
+import { SchemaValidator, StoreDocument } from "@effected/schemastore";
+import { Effect, Schema } from "effect";
 
 const program = Effect.gen(function* () {
   const validator = yield* SchemaValidator;
@@ -191,15 +176,21 @@ const program = Effect.gen(function* () {
   return yield* validator.validate(document.toJson());
 });
 
-Effect.runPromise(Effect.provide(program, AjvValidator)).then(console.log);
+Effect.runPromise(Effect.provide(program, SchemaValidator.layer)).then(console.log);
 // [] when the document compiles clean; the engine's findings otherwise
 ```
 
+The service stays an interface: `noop` switches validation off deliberately, `makeTest` / `layerTest` are the doubles (unstubbed members die naming themselves) and a consumer standardized on another engine can substitute one. `DocumentLint` remains the engine-free structural half, answering SchemaStore hygiene questions ajv does not.
+
 `validate` takes the flat serialized record — `StoreDocument.toJson()`'s shape — so the seam stays engine-shaped and decoupled from this package's classes.
 
 ## Writing schema files
 
-`SchemaFile` is the package's one IO surface: serialize through the canonical serializer, compare against what is on disk and write only on difference, creating parent directories as needed. The outcome is a value, so a generator committed to a repo does not churn mtimes, and a CI drift check is `read` plus compare:
+`SchemaFile` is the package's one IO surface: serialize through the canonical serializer, compare against what is on disk and write only on difference, creating parent directories as needed. The result is a value, never a log.
+
+The comparison is by **content**, not bytes, so a generated schema can share a file with a formatter that also owns it. If your repo's Biome or Prettier hook reflows the emitted JSON, the next run still reports `"unchanged"` and leaves the file alone, and you write no exclusion rule. Pass `compare: "bytes"` to opt back into byte-exactness when the emitted text is itself the artifact.
+
+`write` also says what the difference *meant*: `"annotations"` when only prose and editor affordances moved, so the document replaces its predecessor transparently and needs no new version, and `"contract"` when an assertion keyword moved and a consumer's valid document may now be invalid. `check` makes the same comparison without writing, which is what a CI drift job wants:
 
 ```ts
 import { SchemaFile, StoreDocument } from "@effected/schemastore";
@@ -213,32 +204,89 @@ const program = Effect.gen(function* () {
   });
   const first = yield* files.write("schemas/config.schema.json", document);
   const second = yield* files.write("schemas/config.schema.json", document);
-  return [first, second] as const;
+  const drift = yield* files.check("schemas/config.schema.json", document);
+  return [first, second, drift] as const;
 }).pipe(
   Effect.provide(SchemaFile.layer),
   Effect.provide(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer)),
 );
 
 Effect.runPromise(program).then(console.log);
-// => ["written", "unchanged"]
+// => [
+//      { outcome: "written", change: "created" },
+//      { outcome: "unchanged", change: "none" },
+//      { wouldWrite: false, change: "none" },
+//    ]
 ```
 
+`outcome` and `wouldWrite` are the authoritative answers to whether the file was or would be touched. Never infer that from `change`, which reports content and reads `"none"` on a `compare: "bytes"` write that did rewrite the file.
+
 Failures stay typed and apart: `SchemaFileNotFoundError` for a missing file on `read`, `SchemaFileReadError` when the comparison read fails for any other reason (the write fails rather than silently overwriting), `SchemaFileWriteError` for the filesystem write and `CanonicalJsonError` when the document does not serialize.
 
+## The emit pipeline
+
+`SchemaPipeline` is the loop around everything above: generate each target's document, lint it, validate it with the engine, gate on the findings, write it. It is a plain function requiring `SchemaFile` and `SchemaValidator`, not another service to wire.
+
+```ts
+import { SchemaFile, SchemaPipeline, SchemaTarget, SchemaValidator } from "@effected/schemastore";
+import { NodeServices } from "@effect/platform-node";
+import { Effect, Layer, Schema } from "effect";
+
+const targets = [
+  SchemaTarget.make({
+    schema: Schema.Struct({ name: Schema.String }),
+    $id: "https://example.com/config.schema.json",
+    path: "schemas/config.schema.json",
+  }),
+];
+
+const program = SchemaPipeline.run(targets).pipe(
+  Effect.provide(Layer.mergeAll(SchemaFile.layer, SchemaValidator.layer)),
+  Effect.provide(NodeServices.layer),
+);
+
+Effect.runPromise(program).then(console.log);
+// => [{ $id, path, outcome: "written", change: "created", findings: [] }]
+```
+
+A target names its schema, its `$id` and where the file goes. `name` is optional and only catalog naming reads it, so a file-only target like the one above does not repeat its path's basename; supply it when you also pass a `version`, since versioned naming is `<name>-<version>.json`.
+
+Both gates' findings normalize into one `PipelineFinding` shape, so a single predicate judges them. Gating is **policy, not mechanism**: `blocking` defaults to `severity === "warning"`, which is what `UnresolvedRef`, `UnknownKeyword` and `DepthExceeded` are. Replace the predicate rather than the loop when you disagree.
+
+```ts
+SchemaPipeline.run(targets, { blocking: (finding) => finding.source === "validator" });
+```
+
+Worth knowing which gate actually stops you here. A target carries a `Schema`, so pipeline documents come from `fromSchema`, and the Draft-07 lowering drops undeclared keywords before the lint ever sees them: `UnknownKeyword` is effectively unreachable through this entry point and **the engine gate is what blocks in practice**. The lint's warning checks earn their keep on depth and on documents the pipeline did not build, such as a hand-assembled `StoreDocument.draft07` or one read back off disk.
+
+Findings come back as values and are never logged, so the wording of your build output stays yours. A blocking finding fails with `SchemaGateError` carrying every finding that blocked, and the run stops there — a gated document is never written, and neither are the targets after it.
+
+`SchemaPipeline.check(targets)` is the same walk with no writes, answering `wouldWrite`, `change` and `blocked` per target. Where `run` enforces, `check` reports: it is total over the targets and never stops at a failing gate, so a repo with several broken documents learns about all of them in one run rather than one per run. A blocked target is still never mistaken for clean drift, because `blocked` says so.
+
+`runOne` and `checkOne` take a single target and answer its one result directly, so a one-target caller need not prove element zero exists.
+
+## Comparing two documents
+
+`DocumentDiff.classify` is the pure form of the comparison `SchemaFile` makes internally: hand it two emitted documents and it answers `"none"`, `"annotations"` or `"contract"`. That is the signal for whether a change needs a new schema version — `"annotations"` replaces its predecessor transparently, `"contract"` does not. `DocumentDiff.isClean` is the predicate for the clean case, so consumers do not spell `"none"` themselves; `"created"` is deliberately not clean.
+
+The classification is key-order insensitive and keyword-position aware, like the lint. `default`, `examples`, `readOnly` and `writeOnly` count as contract rather than documentation, because consumers act on them: reporting a contract change as annotations ships a silent break, while the reverse only costs a version bump.
+
 ## Canonical JSON
 
 `CanonicalJson` is the deterministic serializer behind `serializeResult` and `SchemaFile.write`: insertion-order keys (assembly owns ordering — nothing is sorted), tab indentation by default, LF line endings and a single trailing newline, so equal documents serialize to equal bytes. Where `JSON.stringify` silently drops or rewrites `undefined`, `NaN` and non-plain objects, it fails typed instead — `NonJsonValueError` carries a JSON pointer to the offending value, and `JsonDepthExceededError` catches hostile nesting and cycles.
 
 ## Features
 
-- `StoreDocument` — the assembly pipeline: `fromSchema` / `fromSchemaResult`, the flat `toJson()` publication shape, `serializeResult()`, the `DRAFT_07_META_SCHEMA` constant and `SchemaConversionError`.
+- `StoreDocument` — the assembly pipeline: `fromSchema` / `fromSchemaResult`, the `draft07` constructor for hand-built documents, the flat `toJson()` publication shape, `serializeResult()`, the `DRAFT_07_META_SCHEMA` constant and `SchemaConversionError`.
 - `AnnotationCarriers` / `KeywordFamilies` — the post-lowering re-graft and the one registry of declared keyword families, consumed by both the carriers and the lint so they cannot disagree.
-- `SchemaVersioning` / `SchemaVersion` — the store-native label grammar with `parseResult` / `parse`, the `Order` instance and `latest`, plus `fileName`, `schemaUrl` and `catalogUrls` deriving both catalog modes.
-- `CatalogEntry` — the `catalog.json` entry as a `Schema.Class`, `assemble`, and the `fileMatch` hygiene lint (`CatalogLintFinding`).
+- `SchemaVersioning` / `SchemaVersion` — full-SemVer version labels with `parseResult` / `parse`, the `Order` instance and `latest`, plus `fileName`, `schemaUrl` and `catalogUrls` deriving both catalog modes.
+- `CatalogEntry` — the `catalog.json` entry as a `Schema.Class`, `assemble` and the `fileMatch` hygiene lint (`CatalogLintFinding`).
 - `DocumentLint` — the total structural lint returning `DocumentLintFinding` values, never an error.
-- `SchemaValidator` — the real-engine contract seam: `ValidationFinding`, `SchemaValidatorError`, `noop` and the `makeTest` / `layerTest` doubles.
-- `SchemaFile` — write-if-changed IO over core `FileSystem` / `Path`, answering `"written" | "unchanged"` as a value.
-- `SchemaTarget` — the target manifest vocabulary: schema, `$id`, name, destination path and optional version.
+- `SchemaValidator` — real-engine validation, closed by default over ajv: provide `SchemaValidator.layer` and it works. `ValidationFinding`, `SchemaValidatorError`, `noop` to switch validation off and the `makeTest` / `layerTest` doubles.
+- `DocumentDiff` — `classify` puts two documents in `"none"` / `"annotations"` / `"contract"`, the signal for whether a change needs a new schema version, plus `isClean` for the clean case.
+- `SchemaPipeline` — the emit loop over a target manifest: `run` and `check`, the single-target `runOne` and `checkOne`, `PipelineFinding`, `SchemaGateError` and an overridable gating predicate.
+- `SchemaFile` — write-if-changed IO over core `FileSystem` / `Path`, comparing by content and answering what changed as a value; `check` is the non-writing drift half, answering `wouldWrite` alongside `change`.
+- `SchemaTarget` — the target manifest vocabulary: schema, `$id`, destination path, an optional name and an optional version that requires one.
 - `CanonicalJson` — the deterministic serializer with typed failures (`NonJsonValueError`, `JsonDepthExceededError`).
 
 ## License

package/SchemaFile.js

@@ -1,3 +1,4 @@
+import { DocumentDiff } from "./DocumentDiff.js";
 import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
 
 //#region src/SchemaFile.ts
@@ -53,10 +54,14 @@ var SchemaFileWriteError = class extends Schema.TaggedErrorClass()("SchemaFileWr
 * services; provide `@effect/platform-node`'s `NodeFileSystem` / `NodePath`
 * (or a bun equivalent) at the application boundary.
 *
-* `write` is write-if-changed: serialization goes through the owned
-* `CanonicalJson` (equal documents serialize to equal bytes), so an
-* unchanged document never touches the file — a generator committed to a
-* repo does not churn mtimes, and its CI drift check is `read` + compare.
+* `write` is write-if-changed, and by default compares **content**: an
+* unchanged document never touches the file even if another tool has
+* reformatted it, so a generator committed to a repo whose pre-commit hook
+* formats JSON does not churn on every run. It also reports what the
+* difference meant — `"annotations"` (prose only, replaces its predecessor
+* transparently) versus `"contract"` (an assertion moved, so a new
+* `SchemaVersioning` version is warranted). `check` makes the same
+* comparison without writing, which is what a CI drift job wants.
 *
 * @example
 * ```ts
@@ -83,19 +88,44 @@ var SchemaFile = class SchemaFile extends Context.Service()("@effected/schemasto
 	static make = Effect.gen(function* () {
 		const fs = yield* FileSystem.FileSystem;
 		const path = yield* Path.Path;
+		const read = Effect.fn("SchemaFile.read")(function* (target) {
+			return yield* fs.readFileString(target).pipe(Effect.mapError((cause) => cause.reason._tag === "NotFound" ? SchemaFileNotFoundError.make({ path: target }) : SchemaFileReadError.make({
+				path: target,
+				cause
+			})));
+		});
+		const readForCompare = (target) => fs.readFileString(target).pipe(Effect.catch((cause) => cause.reason._tag === "NotFound" ? Effect.succeed(void 0) : Effect.fail(SchemaFileReadError.make({
+			path: target,
+			cause
+		}))));
+		const classify = (existing, text) => {
+			try {
+				return DocumentDiff.classify(JSON.parse(existing), JSON.parse(text));
+			} catch {
+				return "contract";
+			}
+		};
+		const compare = (existing, text, options) => {
+			if (existing === void 0) return {
+				wouldWrite: true,
+				change: "created"
+			};
+			const change = classify(existing, text);
+			return {
+				wouldWrite: options?.compare === "bytes" ? existing !== text : change !== "none",
+				change
+			};
+		};
 		return {
-			read: Effect.fn("SchemaFile.read")(function* (target) {
-				return yield* fs.readFileString(target).pipe(Effect.mapError((cause) => cause.reason._tag === "NotFound" ? SchemaFileNotFoundError.make({ path: target }) : SchemaFileReadError.make({
-					path: target,
-					cause
-				})));
-			}),
+			read,
 			write: Effect.fn("SchemaFile.write")(function* (target, document, options) {
 				const text = yield* Effect.fromResult(document.serializeResult(options));
-				if ((yield* fs.readFileString(target).pipe(Effect.catch((cause) => cause.reason._tag === "NotFound" ? Effect.succeed(void 0) : Effect.fail(SchemaFileReadError.make({
-					path: target,
-					cause
-				}))))) === text) return "unchanged";
+				const existing = yield* readForCompare(target);
+				const { wouldWrite, change } = compare(existing, text, options);
+				if (!wouldWrite) return {
+					outcome: "unchanged",
+					change
+				};
 				yield* fs.makeDirectory(path.dirname(target), { recursive: true }).pipe(Effect.mapError((cause) => SchemaFileWriteError.make({
 					path: target,
 					cause
@@ -104,7 +134,15 @@ var SchemaFile = class SchemaFile extends Context.Service()("@effected/schemasto
 					path: target,
 					cause
 				})));
-				return "written";
+				return {
+					outcome: "written",
+					change
+				};
+			}),
+			check: Effect.fn("SchemaFile.check")(function* (target, document, options) {
+				const text = yield* Effect.fromResult(document.serializeResult(options));
+				const existing = yield* readForCompare(target);
+				return compare(existing, text, options);
 			})
 		};
 	});