@effected/schemastore 0.9.1 → 0.10.0

package/CanonicalJson.js

@@ -1,4 +1,4 @@
-import { Effect, Result, Schema } from "effect";
+import { Effect, JsonPointer, Result, Schema } from "effect";
 
 //#region src/CanonicalJson.ts
 /**
@@ -48,7 +48,24 @@ var SerializeFailure = class {
 		this.error = error;
 	}
 };
-const escapePointerSegment = (segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1");
+const EQUALITY_STACK_GUARD = 256 * 8;
+const isPlainRecord = (node) => {
+	if (typeof node !== "object" || node === null || Array.isArray(node)) return false;
+	const prototype = Object.getPrototypeOf(node);
+	return prototype === Object.prototype || prototype === null;
+};
+const contentEqual = (a, b, depth) => {
+	if (a === b) return true;
+	if (depth >= EQUALITY_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) => contentEqual(element, b[index], depth + 1));
+	}
+	if (!isPlainRecord(a) || !isPlainRecord(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) && contentEqual(a[key], b[key], depth + 1));
+};
 /**
 * Deterministic, canonical JSON text: the package's owned serializer, so a
 * consumer never shells out to an external formatter to produce a stable
@@ -89,6 +106,24 @@ var CanonicalJson = class CanonicalJson {
 	* primitive — synchronous callers can use that variant directly.
 	*/
 	static serialize = Effect.fn("CanonicalJson.serialize")((value, options) => Effect.fromResult(CanonicalJson.serializeResult(value, options)));
+	/**
+	* Content equality under the serializer's own semantics: two values are
+	* equal when they would parse to the same JSON document — object key
+	* order is a serialization detail and is ignored, array order is data
+	* and is not. `NaN` is never equal to itself (it is not JSON). The same
+	* reference compares `true` before any structural walk — so a cyclic
+	* value equals itself — and the comparison is total: two distinct
+	* cyclic or hostile-depth values report `false` at the stack guard
+	* rather than overflowing.
+	*
+	* This is the comparison `SchemaFile`'s write-if-changed and
+	* `DocumentDiff`'s leaf comparison already make, exported so a consumer
+	* writing its own JSON artifact (a catalog entry) can decide "unchanged"
+	* by the same rule instead of re-implementing it.
+	*/
+	static equals(left, right) {
+		return contentEqual(left, right, 0);
+	}
 };
 const indentUnit = (indent) => {
 	if (!Number.isInteger(indent) || indent < 0) throw new Error(`indent must be "tab" or a non-negative integer space count, got ${indent}`);
@@ -128,7 +163,7 @@ const emit = (value, path, depth, unit) => {
 	}));
 	const entries = Object.entries(value);
 	if (entries.length === 0) return "{}";
-	return `{\n${entries.map(([key, member]) => `${indent}${JSON.stringify(key)}: ${emit(member, `${path}/${escapePointerSegment(key)}`, depth + 1, unit)}`).join(",\n")}\n${closing}}`;
+	return `{\n${entries.map(([key, member]) => `${indent}${JSON.stringify(key)}: ${emit(member, `${path}/${JsonPointer.escapeToken(key)}`, depth + 1, unit)}`).join(",\n")}\n${closing}}`;
 };
 
 //#endregion

package/DocumentDiff.js

@@ -1,3 +1,4 @@
+import { CanonicalJson } from "./CanonicalJson.js";
 import { KeywordFamilies } from "./KeywordFamilies.js";
 
 //#region src/DocumentDiff.ts
@@ -28,19 +29,6 @@ const SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
 	"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";
@@ -49,8 +37,8 @@ const worst = (left, right) => {
 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";
+	if (depth >= 256) return CanonicalJson.equals(a, b) ? "none" : "contract";
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return CanonicalJson.equals(a, b) ? "none" : "contract";
 	let change = "none";
 	const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
 	for (const key of keys) {
@@ -62,7 +50,7 @@ const compareSchema = (a, b, depth) => {
 		const left = a[key];
 		const right = b[key];
 		if (isAnnotationKey(key)) {
-			change = worst(change, deepEqual(left, right, depth) ? "none" : "annotations");
+			change = worst(change, CanonicalJson.equals(left, right) ? "none" : "annotations");
 			continue;
 		}
 		if (SCHEMA_MAP_KEYWORDS.has(key)) change = worst(change, compareSchemaMap(left, right, depth + 1));
@@ -70,13 +58,13 @@ const compareSchema = (a, b, depth) => {
 		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");
+		else change = worst(change, CanonicalJson.equals(left, right) ? "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";
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return CanonicalJson.equals(a, b) ? "none" : "contract";
 	let change = "none";
 	const names = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
 	for (const name of names) {
@@ -96,14 +84,14 @@ const compareSchemaArray = (a, b, depth) => {
 	return change;
 };
 const compareDependencies = (a, b, depth) => {
-	if (!isSchemaObject(a) || !isSchemaObject(b)) return deepEqual(a, b, depth) ? "none" : "contract";
+	if (!isSchemaObject(a) || !isSchemaObject(b)) return CanonicalJson.equals(a, b) ? "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));
+		change = worst(change, Array.isArray(left) || Array.isArray(right) ? CanonicalJson.equals(left, right) ? "none" : "contract" : compareSchema(left, right, depth + 1));
 		if (change === "contract") return "contract";
 	}
 	return change;

package/DocumentLint.js

@@ -1,5 +1,5 @@
 import { KeywordFamilies } from "./KeywordFamilies.js";
-import { Schema } from "effect";
+import { JsonPointer, Schema } from "effect";
 
 //#region src/DocumentLint.ts
 /**
@@ -74,14 +74,20 @@ const DRAFT_07_KEYWORDS = /* @__PURE__ */ new Set([
 	"writeOnly"
 ]);
 const URL_LINE = /^https?:\/\/\S+$/;
-const escapePointerSegment = (segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1");
-const unescapePointerSegment = (segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~");
 const isSchemaObject = (node) => typeof node === "object" && node !== null && !Array.isArray(node);
+const localPointer = (ref) => {
+	if (!ref.startsWith("#/")) return;
+	try {
+		return ref.slice(2).split("/").map((token) => JsonPointer.unescapeToken(decodeURIComponent(token)));
+	} catch {
+		return;
+	}
+};
 const checkRef = (value, path, context) => {
 	if (typeof value !== "string") return;
 	if (value === "#") return;
-	const match = /^#\/\$defs\/([^/]+)/.exec(value);
-	if (match !== null && Object.hasOwn(context.defs, unescapePointerSegment(match[1]))) return;
+	const pointer = localPointer(value);
+	if (pointer !== void 0 && pointer.length >= 2 && pointer[0] === "$defs" && Object.hasOwn(context.defs, pointer[1])) return;
 	context.findings.push(DocumentLintFinding.make({
 		check: "UnresolvedRef",
 		severity: "warning",
@@ -89,6 +95,24 @@ const checkRef = (value, path, context) => {
 		message: `$ref "${value}" does not resolve against the document's $defs pool`
 	}));
 };
+const describedNode = (document) => {
+	const keys = Object.keys(document.root);
+	if (keys.length !== 1 || keys[0] !== "$ref" || typeof document.root.$ref !== "string") return {
+		node: document.root,
+		path: ""
+	};
+	const pointer = localPointer(document.root.$ref);
+	if (pointer === void 0 || pointer.length !== 2 || pointer[0] !== "$defs") return {
+		node: document.root,
+		path: ""
+	};
+	const name = pointer[1];
+	const entry = Object.hasOwn(document.defs, name) ? document.defs[name] : void 0;
+	return isSchemaObject(entry) ? {
+		node: entry,
+		path: `/$defs/${JsonPointer.escapeToken(name)}`
+	} : void 0;
+};
 const lintSchema = (node, path, depth, context) => {
 	if (!isSchemaObject(node)) return;
 	if (depth >= 256) {
@@ -101,7 +125,7 @@ const lintSchema = (node, path, depth, context) => {
 		return;
 	}
 	for (const [key, value] of Object.entries(node)) {
-		const keyPath = `${path}/${escapePointerSegment(key)}`;
+		const keyPath = `${path}/${JsonPointer.escapeToken(key)}`;
 		if (!DRAFT_07_KEYWORDS.has(key) && !KeywordFamilies.isDeclared(key)) {
 			context.findings.push(DocumentLintFinding.make({
 				check: "UnknownKeyword",
@@ -119,11 +143,11 @@ const lintSchema = (node, path, depth, context) => {
 			case "patternProperties":
 			case "$defs":
 			case "definitions":
-				if (isSchemaObject(value)) for (const [name, subschema] of Object.entries(value)) lintSchema(subschema, `${keyPath}/${escapePointerSegment(name)}`, depth + 1, context);
+				if (isSchemaObject(value)) for (const [name, subschema] of Object.entries(value)) lintSchema(subschema, `${keyPath}/${JsonPointer.escapeToken(name)}`, depth + 1, context);
 				break;
 			case "dependencies":
 				if (isSchemaObject(value)) {
-					for (const [name, dependency] of Object.entries(value)) if (!Array.isArray(dependency)) lintSchema(dependency, `${keyPath}/${escapePointerSegment(name)}`, depth + 1, context);
+					for (const [name, dependency] of Object.entries(value)) if (!Array.isArray(dependency)) lintSchema(dependency, `${keyPath}/${JsonPointer.escapeToken(name)}`, depth + 1, context);
 				}
 				break;
 			case "items":
@@ -162,10 +186,18 @@ const lintSchema = (node, path, depth, context) => {
 *   non-standard families ({@link KeywordFamilies}: `x-taplo*`, `x-tombi-*`,
 *   `x-intellij-*`, `x-ai-*` and the vscode set), which ajv strict mode would reject.
 * - `DescriptionWithoutUrl` — advisory: SchemaStore's description
-*   convention ends the root description with a docs URL line.
+*   convention ends the root description with a docs URL line. Read from
+*   the root, or from the `$defs` entry a bare local `$ref` root names —
+*   where assembly places a root annotation.
 *
-* Tractable because the input is bounded `toJsonSchemaDocument` output;
-* this is not a general JSON Schema validator.
+* Tractable because the input is the bounded {@link StoreDocument} shape,
+* not because assembly built it: the warning checks earn their keep on a
+* document the pipeline did not build — hand-assembled through
+* `StoreDocument.draft07`, or read back off disk. A local `$defs` pointer
+* is decoded the way ajv decodes it, so no `$ref` into the pool that the
+* engine gate resolves is reported `UnresolvedRef`; a `#/definitions/...`
+* pointer stays a warning on purpose, since the pool lives under `$defs`.
+* This is not a general JSON Schema validator.
 *
 * @public
 */
@@ -181,15 +213,16 @@ var DocumentLint = class {
 			findings: []
 		};
 		lintSchema(document.root, "", 0, context);
-		for (const [name, definition] of Object.entries(document.defs)) lintSchema(definition, `/$defs/${escapePointerSegment(name)}`, 1, context);
-		const description = document.root.description;
+		for (const [name, definition] of Object.entries(document.defs)) lintSchema(definition, `/$defs/${JsonPointer.escapeToken(name)}`, 1, context);
+		const described = describedNode(document);
+		const description = described?.node.description;
 		if (typeof description === "string") {
 			const lines = description.split("\n");
 			const last = lines[lines.length - 1] ?? "";
 			if (!URL_LINE.test(last.trim())) context.findings.push(DocumentLintFinding.make({
 				check: "DescriptionWithoutUrl",
 				severity: "advisory",
-				path: "/description",
+				path: `${described?.path ?? ""}/description`,
 				message: "SchemaStore's description convention ends with a documentation URL on its own line (<description>\\n<docs-url>)"
 			}));
 		}

package/README.md

@@ -320,6 +320,14 @@ The classification is key-order insensitive and keyword-position aware, like the
 
 `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.
 
+`CanonicalJson.equals` is content equality under the same semantics: two values are equal when they would parse to the same JSON document — object key order is ignored, arrays compare positionally, and a non-plain object (a class instance, a `Date`) compares by reference. It is the comparison `SchemaFile`'s write-if-changed and `DocumentDiff`'s leaf checks already make, exported so a consumer writing its own JSON artifact can decide "unchanged" by the same rule.
+
+## Root annotations
+
+Some annotations cannot be expressed on the source schema — a `Schema.Class` root's `title`, or a description on a field the generator filtered. `rootAnnotations` (on `StoreDocumentOptions`, and forwarded from `SchemaTarget.rootAnnotations` by the pipeline) merges them onto the emitted root after assembly. The gate is up front: only the standard annotation keywords (`title`, `description`, `$comment`, `default`, `examples`, `readOnly`, `writeOnly`, `contentMediaType`, `contentEncoding`) and the declared keyword families are admitted; anything else fails with `UndeclaredAnnotationKeyError` before generation, so the override cannot become a back door for assertion keywords.
+
+Placement follows the assembled root: an inline root takes the annotations directly; a bare local `$ref` root whose `$defs` entry nothing else references takes them on that entry (Draft-07 validators ignore `$ref` siblings); a bare `$ref` root whose entry is shared — a recursive class — becomes `{ ...annotations, allOf: [{ $ref }] }`, so the document is annotated without every occurrence of the type inheriting its title.
+
 ## Features
 
 - `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`.
@@ -331,8 +339,8 @@ The classification is key-order insensitive and keyword-position aware, like the
 - `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, two-phase and all-or-nothing across targets: `run` and `check`, the single-target `runOne` and `checkOne`, `PipelineFinding`, `SchemaGateError` and an overridable gating predicate, plus the contract gate (`ContractChangePolicy`, `ContractChangeTarget`, `SchemaContractChangeError`, `PipelineCheckResult.contractBlocked`) that refuses to rewrite a published document's validation contract in place.
 - `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, an optional version that requires one, and optional per-target `jsonSchema` generation options.
-- `CanonicalJson` — the deterministic serializer with typed failures (`NonJsonValueError`, `JsonDepthExceededError`).
+- `SchemaTarget` — the target manifest vocabulary: schema, `$id`, destination path, an optional name, an optional version that requires one, optional per-target `jsonSchema` generation options and `rootAnnotations` merged onto the emitted root.
+- `CanonicalJson` — the deterministic serializer with typed failures (`NonJsonValueError`, `JsonDepthExceededError`) and `equals`, content equality under the same semantics.
 
 ## License
 

package/SchemaPipeline.js

@@ -197,7 +197,8 @@ var SchemaPipeline = class SchemaPipeline {
 			for (const target of targets) {
 				const document = yield* StoreDocument.fromSchema(target.schema, {
 					$id: target.$id,
-					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {}
+					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {},
+					...target.rootAnnotations !== void 0 ? { rootAnnotations: target.rootAnnotations } : {}
 				});
 				const findings = yield* gather(document, options);
 				yield* gate(target, findings, options);
@@ -253,7 +254,8 @@ var SchemaPipeline = class SchemaPipeline {
 			for (const target of targets) {
 				const document = yield* StoreDocument.fromSchema(target.schema, {
 					$id: target.$id,
-					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {}
+					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {},
+					...target.rootAnnotations !== void 0 ? { rootAnnotations: target.rootAnnotations } : {}
 				});
 				const findings = yield* gather(document, options);
 				const { wouldWrite, change } = yield* files.check(target.path, document, options?.write);

package/SchemaTarget.js

@@ -29,7 +29,8 @@ var SchemaTarget = class {
 			published: options.published ?? false,
 			...options.name !== void 0 ? { name: options.name } : {},
 			...version !== void 0 ? { version } : {},
-			...options.jsonSchema !== void 0 ? { jsonSchema: options.jsonSchema } : {}
+			...options.jsonSchema !== void 0 ? { jsonSchema: options.jsonSchema } : {},
+			...options.rootAnnotations !== void 0 ? { rootAnnotations: options.rootAnnotations } : {}
 		};
 	}
 };

package/SchemaVersioning.js

@@ -209,14 +209,9 @@ var SchemaVersioning = class SchemaVersioning {
 	* a contradiction (versioned mode with no versions) and throws — pass
 	* `undefined` for the unversioned mode.
 	*
-	* Labels are inserted in ascending {@link SchemaVersioning.Order}, but a
-	* bare-major label (`"2"`) is array-index-like, so JavaScript enumerates
-	* it FIRST regardless of insertion order — the serialized order of the
-	* `versions` map is not meaningful when such a label is present. A two-
-	* or three-component label is never integer-like and keeps insertion
-	* order through serialization. Deriving ordering from the labels
-	* themselves (as {@link SchemaVersioning.latest} does) is still the
-	* robust read.
+	* Labels are inserted in ascending {@link SchemaVersioning.Order}; see
+	* {@link CatalogUrls.versions} for why a bare-major key's serialized
+	* position is not meaningful.
 	*/
 	static catalogUrls(options) {
 		const { baseUrl, name, versions } = options;

package/SchemastoreConfig.js

@@ -80,8 +80,11 @@ const defineConfig = (input) => {
 	if (!Array.isArray(input.schemas) || input.schemas.length === 0) throw new Error("defineConfig: at least one schema is required");
 	const drift = decodeOrThrow(DriftSchema, input.drift ?? {}, "drift block");
 	const versions = versionsByName(input.schemas);
-	const catalog = (input.catalog ?? []).map((raw) => {
-		const config = decodeOrThrow(CatalogConfigSchema, raw, `catalog entry "${String(raw.name)}"`);
+	const rawCatalog = input.catalog ?? [];
+	if (!Array.isArray(rawCatalog)) throw new Error("defineConfig: invalid catalog: expected an array of catalog entries");
+	const catalog = rawCatalog.map((raw) => {
+		const label = typeof raw === "object" && raw !== null ? String(raw.name) : String(raw);
+		const config = decodeOrThrow(CatalogConfigSchema, raw, `catalog entry "${label}"`);
 		const found = versions.get(config.name);
 		if (found === void 0) throw new Error(`defineConfig: catalog entry "${config.name}" matches no versioned schema`);
 		return {

package/StoreDocument.js

@@ -1,6 +1,6 @@
 import { CanonicalJson } from "./CanonicalJson.js";
 import { KeywordFamilies } from "./KeywordFamilies.js";
-import { Effect, JsonSchema, Result, Schema } from "effect";
+import { Effect, JsonPointer, JsonSchema, Result, Schema } from "effect";
 
 //#region src/StoreDocument.ts
 /**
@@ -36,7 +36,10 @@ var SchemaConversionError = class extends Schema.TaggedError()("SchemaConversion
 /**
 * Indicates that a caller-supplied `includeAnnotationKey` admitted an
 * annotation key outside the declared keyword families
-* ({@link KeywordFamilies}).
+* ({@link KeywordFamilies}), or that a
+* {@link StoreDocumentOptions.rootAnnotations} override names a key outside
+* the admitted set (the standard annotation keywords plus the declared
+* families).
 *
 * Raised by {@link StoreDocument.fromSchema}. This package emits
 * SchemaStore-compatible documents only, so the declared families are the
@@ -47,7 +50,8 @@ var SchemaConversionError = class extends Schema.TaggedError()("SchemaConversion
 *
 * The predicate itself cannot be introspected, so the offending keys are
 * the ones it actually admitted while the document was being generated: a
-* key the source schema never annotates cannot appear here.
+* key the source schema never annotates cannot appear here. Override keys,
+* by contrast, are checked up front, before anything is generated.
 *
 * @public
 */
@@ -63,6 +67,48 @@ var UndeclaredAnnotationKeyError = class extends Schema.TaggedError()("Undeclare
 	}
 };
 const DEFINITIONS_REF_PREFIX = /^#\/definitions(?=\/|$)/;
+const STANDARD_ANNOTATION_KEYWORDS = /* @__PURE__ */ new Set([
+	"title",
+	"description",
+	"$comment",
+	"default",
+	"examples",
+	"readOnly",
+	"writeOnly",
+	"contentMediaType",
+	"contentEncoding"
+]);
+const countRefs = (node, ref) => {
+	if (Array.isArray(node)) {
+		let count = 0;
+		for (const item of node) count += countRefs(item, ref);
+		return count;
+	}
+	if (typeof node === "object" && node !== null) {
+		let count = 0;
+		for (const [key, value] of Object.entries(node)) {
+			if (KeywordFamilies.isDeclared(key)) continue;
+			count += key === "$ref" && value === ref ? 1 : countRefs(value, ref);
+		}
+		return count;
+	}
+	return 0;
+};
+const applyRootAnnotations = (root, defs, annotations) => {
+	const keys = Object.keys(root);
+	const ref = keys.length === 1 && keys[0] === "$ref" ? root.$ref : void 0;
+	const path = typeof ref === "string" ? JsonPointer.parseUriFragment(ref) : void 0;
+	const pool = path !== void 0 && path.length === 2 && path[0] === "$defs" ? defs[path[1]] : void 0;
+	const entry = typeof pool === "object" && pool !== null && !Array.isArray(pool) ? pool : void 0;
+	const shared = entry !== void 0 && typeof ref === "string" && countRefs(defs, ref) > 0;
+	if (shared) delete root.$ref;
+	const target = entry !== void 0 && !shared ? entry : root;
+	for (const [key, value] of Object.entries(annotations)) {
+		if (value === void 0) continue;
+		target[key] = value;
+	}
+	if (shared) root.allOf = [{ $ref: ref }];
+};
 var RewriteDepthExceeded = class {
 	_tag = "RewriteDepthExceeded";
 };
@@ -153,6 +199,11 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 	*/
 	static fromSchemaResult(source, options) {
 		try {
+			const refusedOverrides = Object.keys(options.rootAnnotations ?? {}).filter((key) => !STANDARD_ANNOTATION_KEYWORDS.has(key) && !KeywordFamilies.isDeclared(key));
+			if (refusedOverrides.length > 0) return Result.fail(UndeclaredAnnotationKeyError.make({
+				$id: options.$id,
+				keys: [...refusedOverrides].sort()
+			}));
 			const userIncludes = options.jsonSchema?.includeAnnotationKey;
 			const undeclared = /* @__PURE__ */ new Set();
 			const document = Schema.toJsonSchemaDocument(source, {
@@ -171,6 +222,7 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 			const root = restoreDefsRefs(lowered.schema, 0);
 			const defs = Object.create(null);
 			for (const [name, definition] of Object.entries(lowered.definitions)) defs[name] = restoreDefsRefs(definition, 1);
+			if (options.rootAnnotations !== void 0) applyRootAnnotations(root, defs, options.rootAnnotations);
 			return Result.succeed(StoreDocument.make({
 				$schema: DRAFT_07_META_SCHEMA,
 				$id: options.$id,

package/index.d.ts

@@ -94,6 +94,22 @@ export declare class CanonicalJson {
    * primitive — synchronous callers can use that variant directly.
    */
   static readonly serialize: (value: unknown, options?: CanonicalJsonOptions | undefined) => Effect.Effect<string, CanonicalJsonError, never>;
+  /**
+   * Content equality under the serializer's own semantics: two values are
+   * equal when they would parse to the same JSON document — object key
+   * order is a serialization detail and is ignored, array order is data
+   * and is not. `NaN` is never equal to itself (it is not JSON). The same
+   * reference compares `true` before any structural walk — so a cyclic
+   * value equals itself — and the comparison is total: two distinct
+   * cyclic or hostile-depth values report `false` at the stack guard
+   * rather than overflowing.
+   *
+   * This is the comparison `SchemaFile`'s write-if-changed and
+   * `DocumentDiff`'s leaf comparison already make, exported so a consumer
+   * writing its own JSON artifact (a catalog entry) can decide "unchanged"
+   * by the same rule instead of re-implementing it.
+   */
+  static equals(left: unknown, right: unknown): boolean;
 }
 //#endregion
 //#region src/DocumentDiff.d.ts
@@ -213,7 +229,10 @@ declare const UndeclaredAnnotationKeyError_base: Schema.Class<UndeclaredAnnotati
 /**
  * Indicates that a caller-supplied `includeAnnotationKey` admitted an
  * annotation key outside the declared keyword families
- * ({@link KeywordFamilies}).
+ * ({@link KeywordFamilies}), or that a
+ * {@link StoreDocumentOptions.rootAnnotations} override names a key outside
+ * the admitted set (the standard annotation keywords plus the declared
+ * families).
  *
  * Raised by {@link StoreDocument.fromSchema}. This package emits
  * SchemaStore-compatible documents only, so the declared families are the
@@ -224,7 +243,8 @@ declare const UndeclaredAnnotationKeyError_base: Schema.Class<UndeclaredAnnotati
  *
  * The predicate itself cannot be introspected, so the offending keys are
  * the ones it actually admitted while the document was being generated: a
- * key the source schema never annotates cannot appear here.
+ * key the source schema never annotates cannot appear here. Override keys,
+ * by contrast, are checked up front, before anything is generated.
  *
  * @public
  */
@@ -258,6 +278,39 @@ interface StoreDocumentOptions {
    * `ToJsonSchemaOptions` passes through, and is best left unset.
    */
   readonly jsonSchema?: Schema.ToJsonSchemaOptions;
+  /**
+   * Annotations merged onto the emitted document's root after assembly —
+   * the escape hatch for a generator-side annotation loss the source
+   * schema cannot express (a filtered field, or a root whose annotations
+   * core does not carry).
+   *
+   * Admitted keys are the standard JSON Schema annotation keywords
+   * (`title`, `description`, `$comment`, `default`, `examples`,
+   * `readOnly`, `writeOnly`, `contentMediaType`, `contentEncoding`) and
+   * the declared keyword families
+   * ({@link KeywordFamilies}); any other key fails the build with
+   * {@link UndeclaredAnnotationKeyError}, so the override cannot become a
+   * back door for assertion keywords. Override keys win over generated
+   * ones. The override is checked before generation, so when both this
+   * gate and the `includeAnnotationKey` gate would fire, the override's
+   * keys are the ones reported and the predicate's are not.
+   *
+   * Placement follows the assembled root's shape, in three cases:
+   *
+   * - An inline root (a `Struct`, a primitive) takes the annotations
+   *   directly.
+   * - A bare local `$ref` root (the shape a `Schema.Class` root produces —
+   *   `{ "$ref": "#/$defs/FooEncoded" }`) whose `$defs` entry has no
+   *   other referent takes them on that entry instead: Draft-07
+   *   validators ignore `$ref` siblings, so the root would carry them
+   *   nowhere.
+   * - A bare local `$ref` root whose entry is shared — a recursive class,
+   *   or one another definition also references — is replaced by
+   *   `{ ...annotations, allOf: [{ "$ref": ... }] }`, so the document is
+   *   annotated without every other occurrence of the type inheriting
+   *   the root's title.
+   */
+  readonly rootAnnotations?: Readonly<Record<string, unknown>>;
 }
 declare const StoreDocument_base: Schema.Class<StoreDocument, Schema.Struct<{
   /** The meta-schema URL ({@link DRAFT_07_META_SCHEMA}). */
@@ -726,14 +779,9 @@ export declare class SchemaVersioning {
    * a contradiction (versioned mode with no versions) and throws — pass
    * `undefined` for the unversioned mode.
    *
-   * Labels are inserted in ascending {@link SchemaVersioning.Order}, but a
-   * bare-major label (`"2"`) is array-index-like, so JavaScript enumerates
-   * it FIRST regardless of insertion order — the serialized order of the
-   * `versions` map is not meaningful when such a label is present. A two-
-   * or three-component label is never integer-like and keeps insertion
-   * order through serialization. Deriving ordering from the labels
-   * themselves (as {@link SchemaVersioning.latest} does) is still the
-   * robust read.
+   * Labels are inserted in ascending {@link SchemaVersioning.Order}; see
+   * {@link CatalogUrls.versions} for why a bare-major key's serialized
+   * position is not meaningful.
    */
   static catalogUrls(options: {
     readonly baseUrl: string;
@@ -845,10 +893,18 @@ export declare class DocumentLintFinding extends DocumentLintFinding_base {}
  *   non-standard families ({@link KeywordFamilies}: `x-taplo*`, `x-tombi-*`,
  *   `x-intellij-*`, `x-ai-*` and the vscode set), which ajv strict mode would reject.
  * - `DescriptionWithoutUrl` — advisory: SchemaStore's description
- *   convention ends the root description with a docs URL line.
- *
- * Tractable because the input is bounded `toJsonSchemaDocument` output;
- * this is not a general JSON Schema validator.
+ *   convention ends the root description with a docs URL line. Read from
+ *   the root, or from the `$defs` entry a bare local `$ref` root names —
+ *   where assembly places a root annotation.
+ *
+ * Tractable because the input is the bounded {@link StoreDocument} shape,
+ * not because assembly built it: the warning checks earn their keep on a
+ * document the pipeline did not build — hand-assembled through
+ * `StoreDocument.draft07`, or read back off disk. A local `$defs` pointer
+ * is decoded the way ajv decodes it, so no `$ref` into the pool that the
+ * engine gate resolves is reported `UnresolvedRef`; a `#/definitions/...`
+ * pointer stays a warning on purpose, since the pool lives under `$defs`.
+ * This is not a general JSON Schema validator.
  *
  * @public
  */
@@ -1068,6 +1124,12 @@ export interface SchemaTarget {
    * `includeAnnotationKey` gate this option is also subject to.
    */
   readonly jsonSchema?: Schema.ToJsonSchemaOptions;
+  /**
+   * Forwarded to {@link StoreDocumentOptions.rootAnnotations}; a
+   * target-level field for the same self-describing reason as
+   * `jsonSchema`.
+   */
+  readonly rootAnnotations?: Readonly<Record<string, unknown>>;
 }
 /**
  * Constructors for `SchemaTarget` values.
@@ -1087,6 +1149,7 @@ export declare class SchemaTarget {
     readonly path: string;
     readonly published?: boolean;
     readonly jsonSchema?: Schema.ToJsonSchemaOptions;
+    readonly rootAnnotations?: Readonly<Record<string, unknown>>;
   }): SchemaTarget;
   /**
    * Builds a versioned target. `name` is **required** here: versioned
@@ -1103,6 +1166,7 @@ export declare class SchemaTarget {
     readonly version: SchemaVersion | string;
     readonly published?: boolean;
     readonly jsonSchema?: Schema.ToJsonSchemaOptions;
+    readonly rootAnnotations?: Readonly<Record<string, unknown>>;
   }): SchemaTarget;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore",
-	"version": "0.9.1",
+	"version": "0.10.0",
 	"private": false,
 	"description": "Build, validate, version and publish SchemaStore-shaped Draft-07 JSON Schema documents from Effect Schema sources: document assembly, ajv strict-mode validation, structural lints, catalog entries, canonical JSON and a content-comparing emit pipeline.",
 	"keywords": [