@effected/schemastore 0.3.0 → 0.5.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,6 +18,43 @@
 * - **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
@@ -31,7 +70,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 +79,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

@@ -8,7 +8,7 @@
 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
+> development against a single pinned Effect v4 prerelease. Packages graduate to
 > `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
 > exactly the ones the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
@@ -106,10 +106,14 @@ console.log(Effect.runSync(program));
 
 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.
 
+`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
@@ -270,9 +274,32 @@ SchemaPipeline.run(targets, { blocking: (finding) => finding.source === "validat
 
 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.
+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.
+
+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 +316,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.
+- `AnnotationCarriers` / `KeywordFamilies` — the post-lowering re-graft and the one registry of declared keyword families (upstream language-server families plus the house `x-ai-` machine-annotation namespace), 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`, `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.
 	*