@effected/schemastore 0.4.0 → 0.6.0

package/DocumentLint.js

@@ -107,7 +107,7 @@ const lintSchema = (node, path, depth, context) => {
 				check: "UnknownKeyword",
 				severity: "warning",
 				path: keyPath,
-				message: `"${key}" is not a Draft-07 keyword or a declared non-standard family (x-taplo*, x-tombi-*, x-intellij-*, vscode); ajv strict mode rejects it`
+				message: `"${key}" is not a Draft-07 keyword or a declared non-standard family (x-taplo*, x-tombi-*, x-intellij-*, x-ai-*, vscode); ajv strict mode rejects it`
 			}));
 			continue;
 		}
@@ -160,7 +160,7 @@ const lintSchema = (node, path, depth, context) => {
 *   `#/definitions/...` pointer, is a warning).
 * - `UnknownKeyword` — no keyword outside Draft-07 plus the declared
 *   non-standard families ({@link KeywordFamilies}: `x-taplo*`, `x-tombi-*`,
-*   `x-intellij-*` and the vscode set), which ajv strict mode would reject.
+*   `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.
 *

package/KeywordFamilies.js

@@ -1,9 +1,11 @@
 //#region src/KeywordFamilies.ts
 /**
-* The one owner of the declared non-standard keyword families — the
-* language-server keyword sets SchemaStore's CONTRIBUTING enumerates as
-* legitimately consumed by editor toolchains, which ajv strict mode would
-* otherwise reject:
+* The one owner of the declared non-standard keyword families, in two
+* groups.
+*
+* **Upstream language-server families** — mirrored from SchemaStore's
+* CONTRIBUTING, the keyword sets legitimately consumed by editor
+* toolchains that ajv strict mode would otherwise reject:
 *
 * - **vscode-json-languageservice** (exact names): `allowTrailingCommas`,
 *   `defaultSnippets`, `enumDescriptions`, `markdownDescription`,
@@ -16,10 +18,48 @@
 * - **IntelliJ**: the `x-intellij-` prefix (`x-intellij-language-injection`,
 *   `x-intellij-html-description`, `x-intellij-enum-metadata`).
 *
+* **The house machine-annotation family** — `x-ai-` (WITH the trailing
+* dash; bare `x-ai` and a look-alike prefix like `x-aida-foo` are NOT
+* declared), owned by this package rather than mirrored from anywhere:
+*
+* - It is a NAMESPACE, not a vocabulary — any `x-ai-*` key is declared, and
+*   this package does not enumerate specific keys.
+* - The key itself must be one ajv can register: after the prefix, only
+*   `[A-Za-z0-9_$:-]` (ajv holds a keyword name to
+*   `/^[a-z_$][a-z0-9_$:-]*$/i`). A dot, a space, a slash, an `@`, a `+` or
+*   any non-ASCII character makes the engine gate reject the whole document
+*   — as a root-pathed `ValidationFinding`, not an error.
+* - A value under a declared `x-ai-*` key must be JSON — `CanonicalJson`
+*   fails typed (`NonJsonValueError`) on anything else, the same as
+*   every other emitted value.
+* - The one recommended, non-binding key is `x-ai-hint`: a string carrying
+*   an instruction to a machine reader about the annotated value.
+* - `x-ai-example` is deliberately NOT recommended. Draft-07's own
+*   `examples` keyword already exists, is carried by the assembly, and
+*   classifies as a CONTRACT change in `DocumentDiff`; an `x-ai-*`
+*   key classifies as ANNOTATIONS. The two would be two example channels
+*   with opposite version semantics.
+* - A declared-family value must not contain an `$id` — or a repeated
+*   `$anchor` — at ANY depth, not merely as its own top-level key: ajv's
+*   reference collection walks unknown keywords looking for them, so a
+*   colliding one buried anywhere inside an annotation payload fails the
+*   compile, surfacing as a blocking root-pathed `ValidationFinding` rather
+*   than a silent no-op. An empty-string `$id` collides too — it resolves
+*   to the root id.
+* - No upstream tool sanctions `x-ai-`: a document carrying it that is
+*   submitted to schemastore.org needs the corresponding entry added to
+*   that repo's own validation config. Until then it is intended for
+*   self-hosted publication.
+* - `DocumentDiff` classifies a delta confined to `x-ai-*` keys as
+*   `"annotations"`, so adopting the family on an already-published
+*   versioned document rewrites that file in place — correct, because
+*   annotations are transparently replaceable.
+*
 * Both consumers of the registry route through {@link KeywordFamilies.isDeclared}:
 * `DocumentLint`'s `UnknownKeyword` check (a declared key is not flagged) and
-* `AnnotationCarriers` (only declared keys are re-grafted after the Draft-07
-* lowering). One predicate, so the lint and the carriers cannot drift.
+* `StoreDocument.fromSchema`'s gate (a key outside the families fails the
+* build rather than being emitted). One predicate, so the lint and the gate
+* cannot drift.
 */
 const VSCODE_KEYWORDS = /* @__PURE__ */ new Set([
 	"allowTrailingCommas",
@@ -31,7 +71,7 @@ const VSCODE_KEYWORDS = /* @__PURE__ */ new Set([
 /**
 * The declared non-standard keyword families as one predicate: the
 * vscode-json-languageservice set by exact name, plus the `x-taplo`,
-* `x-tombi-` and `x-intellij-` prefixes.
+* `x-tombi-`, `x-intellij-` and `x-ai-` prefixes.
 *
 * @public
 */
@@ -40,10 +80,11 @@ var KeywordFamilies = class {
 	/**
 	* Whether `key` belongs to a declared non-standard keyword family.
 	* Draft-07's own keywords are a separate vocabulary — this predicate
-	* answers only for the language-server extension families.
+	* answers only for the language-server extension families and the
+	* house `x-ai-` machine-annotation namespace.
 	*/
 	static isDeclared(key) {
-		return VSCODE_KEYWORDS.has(key) || key.startsWith("x-taplo") || key.startsWith("x-tombi-") || key.startsWith("x-intellij-");
+		return VSCODE_KEYWORDS.has(key) || key.startsWith("x-taplo") || key.startsWith("x-tombi-") || key.startsWith("x-intellij-") || key.startsWith("x-ai-");
 	}
 };
 

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, 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.
+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), the gate that holds a document's non-standard surface to the language-server keyword families it declares, 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 prerelease. Packages graduate to
@@ -21,7 +21,7 @@ Build, version, validate and lint SchemaStore-shaped Draft-07 JSON Schema docume
 
 ## Why @effected/schemastore
 
-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.
+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 carries unknown and custom keywords through as opaque values — so `markdownDescription`, `x-taplo` and the other editor keywords survive, and the publisher's problem is not getting them through but keeping anything *else* out of a document SchemaStore's own gate would reject. 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 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.
 
@@ -75,7 +75,7 @@ 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.
+`fromSchema` runs the whole pipeline — 2020-12 generation, Draft-07 lowering, the `$ref` rewrite and the declared-family gate — 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.
 
 ## Annotate at the definition site
 
@@ -83,7 +83,7 @@ One constraint bites consumers who do not know it, so it comes before the featur
 
 ## Carrying language-server annotations
 
-SchemaStore documents lean on non-standard keywords the editors read: the vscode-json-languageservice set (`markdownDescription`, `defaultSnippets`, `enumDescriptions`, `markdownEnumDescriptions`, `allowTrailingCommas`), taplo's `x-taplo` keys, tombi's `x-tombi-*` and IntelliJ's `x-intellij-*`. Effect Schema annotations accept arbitrary string keys, so `Schema.String.annotate({ "x-taplo": { ... } })` type-checks with no module augmentation — but core's Draft-07 lowering copies a fixed keyword subset and would drop them. `StoreDocument.fromSchema` re-grafts the declared families onto the lowered document with a parallel walk (`AnnotationCarriers`), so the annotation you wrote is the keyword that ships:
+SchemaStore documents lean on non-standard keywords the editors read: the vscode-json-languageservice set (`markdownDescription`, `defaultSnippets`, `enumDescriptions`, `markdownEnumDescriptions`, `allowTrailingCommas`), taplo's `x-taplo` keys, tombi's `x-tombi-*` and IntelliJ's `x-intellij-*`. Effect Schema annotations accept arbitrary string keys, so `Schema.String.annotate({ "x-taplo": { ... } })` type-checks with no module augmentation, and core's Draft-07 lowering carries the key through as an opaque value — in place, on the node you attached it to. `StoreDocument.fromSchema` admits the declared families unconditionally, so the annotation you wrote is the keyword that ships:
 
 ```ts
 import { StoreDocument } from "@effected/schemastore";
@@ -104,12 +104,18 @@ console.log(Effect.runSync(program));
 // => { name: { type: "string", "x-taplo": { docs: { main: "The display name." } } } }
 ```
 
-The declared families are always admitted — `KeywordFamilies` is the one registry, consumed by both the carriers and the lint, so the two cannot drift on what counts as declared. A caller-supplied `includeAnnotationKey` predicate is consulted in addition, but know the boundary: keys it admits outside the declared families reach the Draft 2020-12 document and are still dropped by the lowering.
+The declared families are always admitted, whatever a caller-supplied `includeAnnotationKey` answers — `KeywordFamilies` is the one registry, consumed by both the gate and the lint, so the two cannot drift on what counts as declared. The predicate's only remaining effect is to fail the build: a key it admits outside the declared families raises `UndeclaredAnnotationKeyError`, naming every offending key. That is deliberate. This package emits SchemaStore-compatible documents only, and the families are the whole non-standard surface it will ship, so a predicate that reaches past them is a mistake worth hearing about rather than a preference worth honouring quietly.
+
+One thing the package does *not* do to a declared-family value is walk inside it. The `#/definitions` → `#/$defs` `$ref` rewrite skips those payloads entirely: they are opaque advice addressed to a language server, so a `$ref`-shaped string inside one means whatever that tool says it means and survives verbatim.
+
+`KeywordFamilies` splits into two groups. The upstream families above are mirrored from SchemaStore's own CONTRIBUTING guide — vocabularies the language servers already read. The `x-ai-` prefix (with the trailing dash — bare `x-ai` and a look-alike like `x-aida-foo` are not declared) is different: a house machine-annotation namespace this package owns rather than mirrors, meant for a machine reader rather than an editor. It is a namespace, not a fixed vocabulary — any key under the prefix is declared, and the one recommended (non-binding) key is `x-ai-hint`, a string instruction to a machine reader about the annotated value. A key under the prefix must be one ajv can register: after `x-ai-` only `[A-Za-z0-9_$:-]` (ajv holds a keyword name to `/^[a-z_$][a-z0-9_$:-]*$/i`), so a dot, a space, a slash, an `@`, a `+` or a non-ASCII character makes the engine gate reject the whole document as a finding. A declared-family value must itself be JSON, and must not contain an `$id` — or a repeated `$anchor` — at any depth, not merely as its own top-level key: ajv's reference collection walks unknown keywords looking for them, and a colliding one fails the compile. An empty-string `$id` resolves to the root id and collides too. No upstream tool sanctions `x-ai-` today, so it is intended for self-hosted publication rather than submission to schemastore.org without that repo's own validation-config entry. Because `x-ai-*` advises a reader rather than asserting anything, `DocumentDiff` classifies it as an annotation: adopting the family on an already-published versioned document rewrites that file in place, the same as any other prose change.
 
 ## 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 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.
 
+`SchemaVersioning.isPinned(version)` answers whether a label names a published document rather than a prerelease — SemVer §9 makes a prerelease's own instability explicit, so a contract change inside one breaks nobody's pin. It is the one predicate the pipeline's contract gate and `SchemaVersioning.next` both read, so the two can never disagree about the same label. `next(current, change)` is the version a `WriteChange` classification calls for: identity for anything but a `"contract"` change on a pinned label, otherwise a MINOR bump on the 0.x line (0.x treats MINOR as the breaking axis) or MAJOR above it — always strictly greater, never a minted prerelease.
+
 `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.
 
 ```ts
@@ -268,11 +274,34 @@ Both gates' findings normalize into one `PipelineFinding` shape, so a single pre
 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.
+Worth knowing which gate actually stops you here. A target carries a `Schema`, so pipeline documents come from `fromSchema`, which never admits an undeclared keyword in the first place: `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. `run` is **two-phase and all-or-nothing across targets**: every target is generated, gated, and — for a target the contract policy guards — classified against its predecessor before any file is touched, and only then are the held documents written, in order. A gate or contract failure on the third target therefore leaves the first two unwritten too, not merely the third; nothing is written unless every target passes both gates.
+
+### The contract gate
+
+A schema with a pinned `version` — `SchemaVersioning.isPinned`'s name for a label with no prerelease — is a published document: consumers pin its URL. `SchemaPipeline.run` will not silently rewrite one in place when the new document's validation contract has moved out from under it: by default (`contractChanges: "block-versioned"`), a `"contract"` change on such a target fails the whole run with `SchemaContractChangeError` before anything is written, carrying every affected target's `$id`, `path`, `version` and the `nextVersion` it should publish under instead (`SchemaVersioning.next`). A target with no `version`, or with a prerelease label, declares its own instability and is rewritten in place as before.
+
+```ts
+import { SchemaContractChangeError, SchemaPipeline } from "@effected/schemastore";
+import { Effect } from "effect";
+
+declare const targets: Parameters<typeof SchemaPipeline.run>[0];
+
+const program = SchemaPipeline.run(targets).pipe(
+  Effect.catchTag("SchemaContractChangeError", (error: SchemaContractChangeError) =>
+    Effect.succeed(
+      error.targets.map((target) => `${target.$id}: ${target.version} -> ${target.nextVersion}`),
+    ),
+  ),
+);
+```
+
+Pass `contractChanges: "allow"` to classify and report only, never refuse — the same behavior the pipeline had before this gate existed. That is also the sanctioned repair path for a published file whose on-disk text no longer parses: `SchemaFile` classifies unparseable text as `"contract"` so a corrupted generated file stays regenerable, and the default policy would otherwise refuse that exact repair.
 
-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.
+The contract gate is only coherent when `version` participates in a target's `path` (`schemas/<version>/<name>-<version>.json`) — a target at a fixed path compares the same file forever, so bumping `version` alone does not move where the next write lands.
 
-`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.
+`SchemaPipeline.check(targets)` is the same walk with no writes, answering `wouldWrite`, `change`, `blocked` and `contractBlocked` per target. Where `run` enforces, `check` reports: it is total over the targets and never stops at a failing gate or a blocked contract, so a repo with several broken documents learns about all of them in one run rather than one per run. `blocked` and `contractBlocked` answer different questions side by side — the first, whether findings would block under `blocking`; the second, whether the contract policy would refuse the write under `contractChanges` — so a drift job can print the right remedy instead of telling a refused target to "just regenerate."
 
 `runOne` and `checkOne` take a single target and answer its one result directly, so a one-target caller need not prove element zero exists.
 
@@ -289,13 +318,13 @@ The classification is key-order insensitive and keyword-position aware, like the
 ## 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`.
-- `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` — full-SemVer version labels with `parseResult` / `parse`, the `Order` instance and `latest`, plus `fileName`, `schemaUrl` and `catalogUrls` deriving both catalog modes.
+- `KeywordFamilies` — the one registry of declared keyword families (upstream language-server families plus the house `x-ai-` machine-annotation namespace), consumed by both the `fromSchema` gate and the lint so they cannot disagree.
+- `SchemaVersioning` / `SchemaVersion` — full-SemVer version labels with `parseResult` / `parse`, the `Order` instance and `latest`, `isPinned` and `next` for the contract-change version bump, 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` — 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.
+- `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 and an optional version that requires one.
 - `CanonicalJson` — the deterministic serializer with typed failures (`NonJsonValueError`, `JsonDepthExceededError`).

package/SchemaPipeline.js

@@ -1,3 +1,4 @@
+import { SchemaVersion, SchemaVersioning } from "./SchemaVersioning.js";
 import { DocumentLint } from "./DocumentLint.js";
 import { SchemaFile } from "./SchemaFile.js";
 import { SchemaValidator } from "./SchemaValidator.js";
@@ -55,7 +56,38 @@ var SchemaGateError = class extends Schema.TaggedError()("SchemaGateError", {
 		return `Schema "${this.$id}" failed its gate with ${this.findings.length} blocking finding(s)`;
 	}
 };
+/**
+* One published document whose validation contract would change.
+*
+* @public
+*/
+var ContractChangeTarget = class extends Schema.Class("ContractChangeTarget")({
+	/** The target's `$id`. */
+	$id: Schema.String,
+	/** The path the document would have been written to. */
+	path: Schema.String,
+	/** The target's pinned label. */
+	version: SchemaVersion,
+	/** The label to publish under instead — {@link SchemaVersioning.next} of `version`. */
+	nextVersion: SchemaVersion
+}) {};
+/**
+* Indicates that at least one published target's contract changed under the
+* active {@link ContractChangePolicy}. Raised BEFORE any target is written
+* and total over the targets, so two broken documents surface in one run.
+*
+* @public
+*/
+var SchemaContractChangeError = class extends Schema.TaggedError()("SchemaContractChangeError", { 
+/** Every published target whose contract would change, in target order. */
+targets: Schema.Array(ContractChangeTarget) }) {
+	get message() {
+		return `${this.targets.length} published schema document(s) would change their validation contract; nothing was written. Bump each target's version, $id and path together — ${this.targets.map((target) => `${target.$id}: ${target.version} → ${target.nextVersion}`).join(", ")} — or pass contractChanges: "allow" to rewrite in place.`;
+	}
+};
 const defaultBlocking = (finding) => finding.severity === "warning";
+const contractGuardApplies = (target, options) => (options?.contractChanges ?? "block-versioned") === "block-versioned" && target.version !== void 0 && SchemaVersioning.isPinned(target.version);
+const contractBlocks = (target, change, options) => contractGuardApplies(target, options) && change === "contract";
 const gather = (document, options) => Effect.gen(function* () {
 	const validator = yield* SchemaValidator;
 	const lint = DocumentLint.lint(document).map((finding) => PipelineFinding.make({
@@ -119,20 +151,72 @@ var SchemaPipeline = class SchemaPipeline {
 	constructor() {}
 	/**
 	* Run every target: build its document, gather both gates' findings,
-	* fail with a {@link SchemaGateError} if any block, and write otherwise.
+	* fail with a {@link SchemaGateError} if any block, refuse a published
+	* target whose contract changed, and write otherwise.
+	*
+	* **The run writes nothing unless every target passes both gates.** It
+	* is two-phase: every target is generated, gated and (for a target the
+	* {@link ContractChangePolicy} guards) compared against its predecessor
+	* before any file is touched, and only then are the held documents
+	* written in target order. A gate failure on the third target therefore
+	* leaves the first two unwritten.
+	*
+	* Phase 2 itself is sequential and **not transactional**: a filesystem or
+	* serialization failure part-way through it leaves the targets already
+	* written in place, with no rollback. The guarantee is "no writes unless
+	* every gate passes", not "every write or none".
+	*
+	* The gates run in a fixed precedence: {@link SchemaGateError} is
+	* fail-fast on the first blocked target, because a document the engine
+	* rejects would never be written under any contract policy, so its
+	* classification is noise. {@link SchemaContractChangeError} is total
+	* over the remaining targets, so two published documents whose contracts
+	* moved surface in one run.
+	*
+	* @example
+	* ```ts
+	* import { SchemaContractChangeError, SchemaPipeline } from "@effected/schemastore";
+	* import { Effect } from "effect";
+	*
+	* declare const targets: Parameters<typeof SchemaPipeline.run>[0];
 	*
-	* Targets are processed in order and the run stops at the first gate
-	* failure — a document that fails its gate is not written, and neither
-	* are the targets after it.
+	* const program = SchemaPipeline.run(targets).pipe(
+	*   Effect.catchTag("SchemaContractChangeError", (error: SchemaContractChangeError) =>
+	*     Effect.succeed(
+	*       error.targets.map((target) => `${target.$id}: ${target.version} -> ${target.nextVersion}`),
+	*     ),
+	*   ),
+	* );
+	* ```
 	*/
 	static run(targets, options) {
 		return Effect.gen(function* () {
 			const files = yield* SchemaFile;
-			const results = [];
+			const held = [];
+			const blocked = [];
 			for (const target of targets) {
 				const document = yield* StoreDocument.fromSchema(target.schema, { $id: target.$id });
 				const findings = yield* gather(document, options);
 				yield* gate(target, findings, options);
+				const version = target.version;
+				if (version !== void 0 && contractGuardApplies(target, options)) {
+					const { change } = yield* files.check(target.path, document, options?.write);
+					if (contractBlocks(target, change, options)) blocked.push(ContractChangeTarget.make({
+						$id: target.$id,
+						path: target.path,
+						version,
+						nextVersion: SchemaVersioning.next(version, "contract")
+					}));
+				}
+				held.push({
+					target,
+					document,
+					findings
+				});
+			}
+			if (blocked.length > 0) return yield* Effect.fail(SchemaContractChangeError.make({ targets: blocked }));
+			const results = [];
+			for (const { target, document, findings } of held) {
 				const { outcome, change } = yield* files.write(target.path, document, options?.write);
 				results.push({
 					$id: target.$id,
@@ -172,6 +256,7 @@ var SchemaPipeline = class SchemaPipeline {
 					path: target.path,
 					wouldWrite,
 					blocked: blockingFindings(findings, options).length > 0,
+					contractBlocked: contractBlocks(target, change, options),
 					change,
 					findings
 				});
@@ -197,4 +282,4 @@ var SchemaPipeline = class SchemaPipeline {
 };
 
 //#endregion
-export { PipelineFinding, SchemaGateError, SchemaPipeline };
+export { ContractChangeTarget, PipelineFinding, SchemaContractChangeError, SchemaGateError, SchemaPipeline };

package/SchemaValidator.js

@@ -95,9 +95,12 @@ var SchemaValidator = class SchemaValidator extends Context.Service()("@effected
 	* `validate` checks the document against the Draft-07 meta-schema and
 	* then compiles it, reporting BOTH as {@link ValidationFinding} values:
 	* meta-schema failures keep ajv's structured `instancePath` and
-	* `keyword`, while a strict-mode rejection (which ajv raises by throwing
-	* at compile time) becomes a root-pathed finding. The error channel
-	* stays reserved for the engine failing as a mechanism.
+	* `keyword`, while a rejection ajv raises by *throwing* becomes a
+	* root-pathed finding — both a strict-mode compile failure and a
+	* declared keyword whose NAME ajv's own grammar
+	* (`/^[a-z_$][a-z0-9_$:-]*$/i`) refuses, such as an `x-ai-*` key
+	* carrying a dot or a space. The error channel stays reserved for the
+	* engine failing as a mechanism.
 	*
 	* `strict` defaults to `true` — SchemaStore's gate. Each call builds its
 	* own ajv instance, so documents sharing an `$id` never collide.
@@ -110,9 +113,9 @@ var SchemaValidator = class SchemaValidator extends Context.Service()("@effected
 			});
 			const declared = /* @__PURE__ */ new Set();
 			collectDeclaredKeywords(document, declared, 0);
-			for (const keyword of declared) ajv.addKeyword({ keyword });
-			if (!ajv.validateSchema(document)) return (ajv.errors ?? []).map(findingFromAjvError);
 			try {
+				for (const keyword of declared) ajv.addKeyword({ keyword });
+				if (!ajv.validateSchema(document)) return (ajv.errors ?? []).map(findingFromAjvError);
 				ajv.compile(document);
 			} catch (cause) {
 				return [ValidationFinding.make({

package/SchemaVersioning.js

@@ -42,6 +42,13 @@ const orderingKey = (label) => {
 	if (Result.isFailure(result)) throw new Error(`SchemaVersion ordering invariant violated for label "${label}"`);
 	return result.success;
 };
+const bumpBreaking = (current, parsed) => {
+	try {
+		return parsed.major === 0 ? parsed.bump.minor() : parsed.bump.major();
+	} catch (cause) {
+		throw new Error(`SchemaVersion bump invariant violated: "${current}" cannot be bumped past Number.MAX_SAFE_INTEGER (${Number.MAX_SAFE_INTEGER})`, { cause });
+	}
+};
 const assertSimpleName = (name) => {
 	if (name.length === 0 || /[/\\\s]/.test(name)) throw new Error(`Schema name must be a non-empty simple file base name, got "${name}"`);
 };
@@ -90,6 +97,55 @@ var SchemaVersioning = class SchemaVersioning {
 		return versions.length === 0 ? Option.none() : Option.some(versions.reduce((max, v) => SchemaVersioning.Order(v, max) > 0 ? v : max));
 	}
 	/**
+	* Whether a label names a pinned, published document — i.e. it is NOT a
+	* prerelease. SemVer §9 makes a prerelease's own instability explicit, so
+	* a contract change inside one is not a break for anyone.
+	*
+	* ONE predicate consumed by two policies so they cannot drift:
+	* `SchemaPipeline`'s `"block-versioned"` guard (a pinned versioned target
+	* refuses an in-place contract change) and {@link SchemaVersioning.next}
+	* (a non-pinned label is not bumped). If the two used different tests, a
+	* caller could be refused a write AND told to keep the same label — a
+	* deadlock.
+	*/
+	static isPinned(version) {
+		return orderingKey(version).prerelease.length === 0;
+	}
+	/**
+	* The version label a change classification calls for. Pure and
+	* synchronous; total over validated labels — a non-label input is a wiring
+	* bug and dies as a defect, the same as {@link SchemaVersioning.Order}.
+	*
+	* - `change !== "contract"` (`"none"`, `"annotations"`, `"created"`) →
+	*   `current`. A created file has no predecessor to break; an annotation
+	*   change is transparently replaceable (`DocumentDiff`).
+	* - `current` is not pinned (a prerelease) → `current`. A prerelease
+	*   declares its own instability; the pipeline's `"block-versioned"`
+	*   policy uses the same {@link SchemaVersioning.isPinned}, so the gate
+	*   and the bump agree.
+	* - `major === 0` → MINOR bump (`0.4.0` → `0.5.0`): on the 0.x line MINOR
+	*   is the breaking axis.
+	* - otherwise → MAJOR bump (`5.0.0` → `6.0.0`).
+	*
+	* The bump's job is to be strictly greater and conspicuous, NOT to encode
+	* SemVer compatibility: `DocumentDiff` cannot tell an added optional
+	* property from a removed required one, so every contract change reads as
+	* breaking. Each label is its own file and URL, so an over-bump costs a
+	* file; an under-bump would overwrite a pinned document. `next` never
+	* introduces a prerelease from a stable input.
+	*
+	* A component that would be bumped past `Number.MAX_SAFE_INTEGER` cannot be
+	* represented, and throws this module's explicit invariant `Error` naming
+	* the label and the ceiling rather than `SemVer.make`'s bare schema failure.
+	*/
+	static next(current, change) {
+		if (change !== "contract" || !SchemaVersioning.isPinned(current)) return current;
+		const label = bumpBreaking(current, orderingKey(current)).toString();
+		const reparsed = SchemaVersioning.parseResult(label);
+		if (Result.isFailure(reparsed)) throw new Error(`SchemaVersion bump invariant violated: "${current}" bumped to "${label}"`);
+		return reparsed.success;
+	}
+	/**
 	* Derives the schema file name for a catalog name: `name.json`
 	* unversioned, `name-<version>.json` versioned.
 	*

package/StoreDocument.js

@@ -1,6 +1,5 @@
-import { KeywordFamilies } from "./KeywordFamilies.js";
-import { AnnotationCarriers } from "./AnnotationCarriers.js";
 import { CanonicalJson } from "./CanonicalJson.js";
+import { KeywordFamilies } from "./KeywordFamilies.js";
 import { Effect, JsonSchema, Result, Schema } from "effect";
 
 //#region src/StoreDocument.ts
@@ -34,21 +33,51 @@ var SchemaConversionError = class extends Schema.TaggedError()("SchemaConversion
 		return `Failed to build SchemaStore document "${this.$id}"`;
 	}
 };
+/**
+* Indicates that a caller-supplied `includeAnnotationKey` admitted an
+* annotation key outside the declared keyword families
+* ({@link KeywordFamilies}).
+*
+* Raised by {@link StoreDocument.fromSchema}. This package emits
+* SchemaStore-compatible documents only, so the declared families are the
+* whole permitted non-standard surface. A key outside them is refused
+* loudly rather than emitted — which would ship a document SchemaStore's
+* own gate rejects — or silently omitted, which would hide the mistake in
+* the caller's predicate.
+*
+* 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.
+*
+* @public
+*/
+var UndeclaredAnnotationKeyError = class extends Schema.TaggedError()("UndeclaredAnnotationKeyError", {
+	/** The `$id` of the document that was being built. */
+	$id: Schema.String,
+	/** The offending keys, deduplicated and sorted. */
+	keys: Schema.Array(Schema.String)
+}) {
+	get message() {
+		const keys = this.keys.map((key) => `"${key}"`).join(", ");
+		return `Document "${this.$id}" admits annotation keys outside the declared families: ${keys}`;
+	}
+};
 const DEFINITIONS_REF_PREFIX = /^#\/definitions(?=\/|$)/;
 var RewriteDepthExceeded = class {
 	_tag = "RewriteDepthExceeded";
 };
-const carry = (source, target) => {
-	const result = AnnotationCarriers.carryResult(source, target);
-	if (Result.isFailure(result)) throw result.failure;
-	return result.success;
-};
 const restoreDefsRefs = (node, depth) => {
 	if (depth >= 256) throw new RewriteDepthExceeded();
 	if (Array.isArray(node)) return node.map((item) => restoreDefsRefs(item, depth + 1));
 	if (typeof node === "object" && node !== null) {
 		const out = Object.create(null);
-		for (const [key, value] of Object.entries(node)) out[key] = key === "$ref" && typeof value === "string" ? value.replace(DEFINITIONS_REF_PREFIX, "#/$defs") : restoreDefsRefs(value, depth + 1);
+		for (const [key, value] of Object.entries(node)) {
+			if (KeywordFamilies.isDeclared(key)) {
+				out[key] = value;
+				continue;
+			}
+			out[key] = key === "$ref" && typeof value === "string" ? value.replace(DEFINITIONS_REF_PREFIX, "#/$defs") : restoreDefsRefs(value, depth + 1);
+		}
 		return out;
 	}
 	return node;
@@ -63,9 +92,17 @@ const restoreDefsRefs = (node, depth) => {
 * `JsonSchema.toDocumentDraft07` lowering, the `#/definitions` →
 * `#/$defs` `$ref` rewrite the lowering makes necessary — so every `$ref`
 * in a built document already resolves against the `$defs` pool — and the
-* {@link AnnotationCarriers} re-graft, so annotated non-standard keyword
-* families ({@link KeywordFamilies}) survive into the built document. The
-* package owns assembly and publication shape, not a JSON Schema engine.
+* gate that holds the document's non-standard surface to the declared
+* keyword families ({@link KeywordFamilies}). The package owns assembly and
+* publication shape, not a JSON Schema engine.
+*
+* Annotated declared-family keys survive into the built document because
+* core's Draft-07 lowering copies unknown and custom keywords through as
+* opaque values, in place, including across the tuple coordinate move
+* (2020-12 `prefixItems[i]` → Draft-07 `items[i]`, trailing `items` →
+* `additionalItems`). This package therefore does no re-grafting of its
+* own; it only declines to rewrite `$ref`-shaped strings *inside* those
+* opaque payloads.
 *
 * @public
 */
@@ -117,14 +154,23 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 	static fromSchemaResult(source, options) {
 		try {
 			const userIncludes = options.jsonSchema?.includeAnnotationKey;
+			const undeclared = /* @__PURE__ */ new Set();
 			const document = Schema.toJsonSchemaDocument(source, {
 				...options.jsonSchema,
-				includeAnnotationKey: (key) => KeywordFamilies.isDeclared(key) || userIncludes?.(key) === true
+				includeAnnotationKey: (key) => {
+					if (KeywordFamilies.isDeclared(key)) return true;
+					if (userIncludes?.(key) === true) undeclared.add(key);
+					return false;
+				}
 			});
+			if (undeclared.size > 0) return Result.fail(UndeclaredAnnotationKeyError.make({
+				$id: options.$id,
+				keys: [...undeclared].sort()
+			}));
 			const lowered = JsonSchema.toDocumentDraft07(document);
-			const root = carry(document.schema, restoreDefsRefs(lowered.schema, 0));
+			const root = restoreDefsRefs(lowered.schema, 0);
 			const defs = Object.create(null);
-			for (const [name, definition] of Object.entries(lowered.definitions)) defs[name] = carry(document.definitions[name], restoreDefsRefs(definition, 1));
+			for (const [name, definition] of Object.entries(lowered.definitions)) defs[name] = restoreDefsRefs(definition, 1);
 			return Result.succeed(StoreDocument.make({
 				$schema: DRAFT_07_META_SCHEMA,
 				$id: options.$id,
@@ -169,4 +215,4 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 };
 
 //#endregion
-export { DRAFT_07_META_SCHEMA, SchemaConversionError, StoreDocument };
+export { DRAFT_07_META_SCHEMA, SchemaConversionError, StoreDocument, UndeclaredAnnotationKeyError };