@effected/schemastore 0.4.0 → 0.6.0

package/index.d.ts

@@ -1,73 +1,4 @@
 import { Context, Effect, FileSystem, Layer, Option, Order, Path, Result, Schema } from "effect";
-//#region src/AnnotationCarriers.d.ts
-declare const CarrierDepthExceededError_base: Schema.Class<CarrierDepthExceededError, Schema.TaggedStruct<"CarrierDepthExceededError", {
-  /** JSON pointer (in the lowered document's coordinates) where the cap was hit. */
-  readonly path: Schema.String;
-  /** The nesting cap that was exceeded. */
-  readonly maxDepth: Schema.Number;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Indicates that the carrier re-graft walk nested past the package's
- * hardening cap (256 levels), which also intercepts cyclic inputs before
- * they can recurse forever.
- *
- * Raised by {@link AnnotationCarriers.carry}.
- *
- * @public
- */
-declare class CarrierDepthExceededError extends CarrierDepthExceededError_base {
-  get message(): string;
-}
-/**
- * Re-grafts the declared non-standard keyword families
- * ({@link KeywordFamilies}) from a Draft 2020-12 schema node onto its
- * lowered Draft-07 counterpart.
- *
- * Why this exists: annotation keys admitted into the Draft 2020-12 document
- * (core's `includeAnnotationKey`) are **dropped by core's Draft-07 lowering**,
- * whose keyword walk copies a fixed subset — verified against the installed
- * beta. Carrying `x-taplo`, `x-tombi-*`, `x-intellij-*` or the vscode set
- * into an emitted SchemaStore document therefore requires this post-lowering
- * step; it cannot ride `ToJsonSchemaOptions` alone.
- *
- * The walk mirrors the lowering's own structural rules, so every carrier
- * lands on the node the annotation was attached to — including the one
- * coordinate move the lowering makes (2020-12 `prefixItems[i]` → Draft-07
- * `items[i]`, trailing `items` → `additionalItems`). Only declared-family
- * keys are copied; nothing else about the target changes.
- *
- * `StoreDocument.fromSchema` applies this automatically to the root schema
- * and every `$defs` pool entry — annotate a schema node
- * (`Schema.String.annotate({ "x-taplo": { hidden: true } })`) and the key
- * appears in the built document. Call this directly only when driving core's
- * pipeline yourself.
- *
- * Know the boundary (core behavior, probed at the installed beta): an
- * annotation must sit on the schema **definition** node. Annotating a
- * hoisted (identifier-carrying) schema at its *usage* site — e.g.
- * `Person.annotate({...})` inside a struct field — reaches neither the
- * `$ref` node nor the pool entry, even in the 2020-12 document, so there is
- * nothing to carry.
- *
- * @public
- */
-declare class AnnotationCarriers {
-  private constructor();
-  /**
-   * Grafts declared-family keys from `source` (a Draft 2020-12 schema
-   * node) onto `target` (its lowered Draft-07 counterpart), returning a
-   * new node. Pure and synchronous — the primitive form;
-   * {@link AnnotationCarriers.carry} is the same walk behind a span.
-   */
-  static carryResult(source: unknown, target: unknown): Result.Result<unknown, CarrierDepthExceededError>;
-  /**
-   * Effect form of {@link AnnotationCarriers.carryResult}, adding only the
-   * `AnnotationCarriers.carry` span. Defined in terms of the `Result`
-   * primitive — synchronous callers can use that variant directly.
-   */
-  static readonly carry: (source: unknown, target: unknown) => Effect.Effect<unknown, CarrierDepthExceededError, never>;
-}
-//#endregion
 //#region src/CanonicalJson.d.ts
 declare const NonJsonValueError_base: Schema.Class<NonJsonValueError, Schema.TaggedStruct<"NonJsonValueError", {
   /** JSON pointer to the offending value (`""` is the document root). */
@@ -87,7 +18,7 @@ declare const NonJsonValueError_base: Schema.Class<NonJsonValueError, Schema.Tag
  *
  * @public
  */
-declare class NonJsonValueError extends NonJsonValueError_base {
+export declare class NonJsonValueError extends NonJsonValueError_base {
   get message(): string;
 }
 declare const JsonDepthExceededError_base: Schema.Class<JsonDepthExceededError, Schema.TaggedStruct<"JsonDepthExceededError", {
@@ -105,7 +36,7 @@ declare const JsonDepthExceededError_base: Schema.Class<JsonDepthExceededError,
  *
  * @public
  */
-declare class JsonDepthExceededError extends JsonDepthExceededError_base {
+export declare class JsonDepthExceededError extends JsonDepthExceededError_base {
   get message(): string;
 }
 /**
@@ -149,7 +80,7 @@ interface CanonicalJsonOptions {
  *
  * @public
  */
-declare class CanonicalJson {
+export declare class CanonicalJson {
   private constructor();
   /**
    * Serializes `value` to canonical JSON text. Pure and synchronous — the
@@ -165,201 +96,6 @@ declare class CanonicalJson {
   static readonly serialize: (value: unknown, options?: CanonicalJsonOptions | undefined) => Effect.Effect<string, CanonicalJsonError, never>;
 }
 //#endregion
-//#region src/SchemaVersioning.d.ts
-declare const InvalidSchemaVersionError_base: Schema.Class<InvalidSchemaVersionError, Schema.TaggedStruct<"InvalidSchemaVersionError", {
-  /** The raw input string that failed to parse. */
-  readonly input: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Indicates that a string is not a valid SchemaStore version label.
- *
- * Raised by {@link SchemaVersioning.parse}.
- *
- * @public
- */
-declare class InvalidSchemaVersionError extends InvalidSchemaVersionError_base {
-  get message(): string;
-}
-/**
- * A schema version label: a branded string holding a **full three-component
- * SemVer** — `major.minor.patch` with an optional prerelease, validated by
- * `@effected/semver` itself. Build metadata is rejected (see below).
- *
- * `1.2` and `1` are NOT accepted, though SchemaStore's own corpus uses such
- * labels: requiring all three components makes a label unambiguous to split
- * back out of `<name>-<version>.json` or its URL, which is what consumers
- * do with it. The file-name convention around the label stays SchemaStore's.
- *
- * The label round-trips verbatim into file names and catalog `versions`
- * keys; ordering parses it directly (see {@link SchemaVersioning.Order}).
- *
- * @public
- */
-declare const SchemaVersion: Schema.brand<Schema.String, "SchemaVersion">;
-/**
- * The type of a validated SchemaStore version label.
- *
- * @public
- */
-type SchemaVersion = typeof SchemaVersion.Type;
-/**
- * The `url`/`versions` half of a catalog entry, as assembled by
- * {@link SchemaVersioning.catalogUrls}.
- *
- * @public
- */
-interface CatalogUrls {
-  /** The catalog `url` — the unversioned file, or the latest versioned file. */
-  readonly url: string;
-  /**
-   * The versioned catalog's `versions` map (label → url), inserted — and,
-   * since a three-component label can never be integer-like, enumerated
-   * and serialized — in ascending version order.
-   */
-  readonly versions?: Readonly<Record<string, string>>;
-}
-/**
- * Both SchemaStore catalog modes as pure derivations: unversioned (a plain
- * `name.json` file, `url` only) and versioned (`name-<version>.json` files
- * — SchemaStore's own suffix convention — a `versions` map, and `url`
- * pointing at the latest version).
- *
- * Version labels are full three-component SemVer, so ordering is plain
- * SemVer precedence: `1.10.0` above `1.9.0`, `2.0.0-beta` below `2.0.0`.
- *
- * @public
- */
-declare class SchemaVersioning {
-  private constructor();
-  /**
-   * Parses a version label. Pure and synchronous — the primitive form;
-   * {@link SchemaVersioning.parse} is the same check behind a span.
-   */
-  static parseResult(input: string): Result.Result<SchemaVersion, InvalidSchemaVersionError>;
-  /**
-   * Effect form of {@link SchemaVersioning.parseResult}, adding only the
-   * `SchemaVersioning.parse` span. Defined in terms of the `Result`
-   * primitive — synchronous callers can use that variant directly.
-   */
-  static readonly parse: (input: string) => Effect.Effect<string & import("effect/Brand").Brand<"SchemaVersion">, InvalidSchemaVersionError, never>;
-  /**
-   * `Order` instance over version labels: plain SemVer precedence.
-   * `1.10.0` sorts above `1.9.0` (numeric, not lexical) and `2.0.0-beta`
-   * below `2.0.0` (prerelease precedence).
-   */
-  static readonly Order: Order.Order<SchemaVersion>;
-  /**
-   * The highest version label by {@link SchemaVersioning.Order}, or
-   * `Option.none()` for an empty collection.
-   */
-  static latest(versions: ReadonlyArray<SchemaVersion>): Option.Option<SchemaVersion>;
-  /**
-   * Derives the schema file name for a catalog name: `name.json`
-   * unversioned, `name-<version>.json` versioned.
-   *
-   * The name must be a simple file base name (no separators, no
-   * whitespace); anything else is a wiring mistake and throws.
-   */
-  static fileName(name: string, version?: SchemaVersion): string;
-  /**
-   * The canonical URL a schema file is hosted at: `baseUrl` joined with
-   * {@link SchemaVersioning.fileName}.
-   */
-  static schemaUrl(baseUrl: string, name: string, version?: SchemaVersion): string;
-  /**
-   * Assembles the `url`/`versions` half of a catalog entry.
-   *
-   * Omitting `versions` selects the unversioned mode (`url` only,
-   * pointing at the plain `name.json`). Providing them selects the
-   * versioned mode: the `versions` map carries every label, and `url`
-   * points at the latest version's file. An **empty** `versions` array is
-   * a contradiction (versioned mode with no versions) and throws — pass
-   * `undefined` for the unversioned mode.
-   *
-   * Labels are inserted in ascending {@link SchemaVersioning.Order} and
-   * stay that way on serialization. Requiring three components is what
-   * buys this: JavaScript enumerates array-index-like keys first, so the
-   * old grammar's bare-major label (`"2"`) jumped ahead of every dotted
-   * one regardless of insertion order. No SemVer label is integer-like,
-   * so that hazard is gone. Deriving ordering from the labels themselves
-   * (as {@link SchemaVersioning.latest} does) is still the robust read.
-   */
-  static catalogUrls(options: {
-    readonly baseUrl: string;
-    readonly name: string;
-    readonly versions?: ReadonlyArray<SchemaVersion>;
-  }): CatalogUrls;
-}
-//#endregion
-//#region src/CatalogEntry.d.ts
-declare const CatalogLintFinding_base: Schema.Class<CatalogLintFinding, Schema.Struct<{
-  /** Which hygiene check fired. */
-  readonly check: Schema.Literals<readonly ["GenericFileMatch", "ComplexFileMatch"]>;
-  /** The `fileMatch` pattern the finding is about. */
-  readonly pattern: Schema.String;
-  /** Human-readable explanation with the SchemaStore rationale. */
-  readonly message: Schema.String;
-}>, {}>;
-/**
- * A fileMatch hygiene finding: a value in a lint report, not an error —
- * SchemaStore reviewers reject entries over these, so surfacing them
- * locally is the point, but a warned entry is still a valid entry.
- *
- * @public
- */
-declare class CatalogLintFinding extends CatalogLintFinding_base {}
-declare const CatalogEntry_base: Schema.Class<CatalogEntry, Schema.Struct<{
-  /** The schema's display name in the catalog. */
-  readonly name: Schema.String;
-  /** The catalog description. */
-  readonly description: Schema.String;
-  /** Glob patterns editors match files against. */
-  readonly fileMatch: Schema.$Array<Schema.String>;
-  /** The schema URL — the unversioned file, or the latest version. */
-  readonly url: Schema.String;
-  /**
-   * Versioned mode only: label → schema URL. Inserted ascending, but key
-   * order is not a contract — bare-major labels enumerate first (see
-   * `SchemaVersioning.catalogUrls`); derive ordering from the labels.
-   */
-  readonly versions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
-}>, {}>;
-/**
- * A SchemaStore `catalog.json` entry: the class is the schema, so decoding
- * an existing entry and encoding one for submission are the same artifact.
- * `versions` is present only for versioned catalogs
- * ({@link SchemaVersioning.catalogUrls} assembles both modes).
- *
- * @public
- */
-declare class CatalogEntry extends CatalogEntry_base {
-  /**
-   * Assembles an entry from a catalog identity plus
-   * {@link SchemaVersioning.catalogUrls}' inputs: pass `versions` for the
-   * versioned mode (the `versions` map and latest-pointing `url` are
-   * derived), omit it for the unversioned mode.
-   */
-  static assemble(options: {
-    readonly name: string;
-    readonly description: string;
-    readonly fileMatch: ReadonlyArray<string>;
-    readonly baseUrl: string;
-    readonly fileBaseName?: string;
-    readonly versions?: ReadonlyArray<SchemaVersion>;
-  }): CatalogEntry;
-  /**
-   * The fileMatch hygiene lint over this entry's patterns — pure shape
-   * analysis (no glob engine): generic patterns SchemaStore rejects and
-   * complex constructs it asks contributors to expand.
-   */
-  lint(): ReadonlyArray<CatalogLintFinding>;
-  /**
-   * {@link CatalogEntry.lint} over a bare pattern list, for callers
-   * checking patterns before an entry exists.
-   */
-  static lintFileMatch(patterns: ReadonlyArray<string>): ReadonlyArray<CatalogLintFinding>;
-}
-//#endregion
 //#region src/DocumentDiff.d.ts
 /**
  * What differs between two schema documents:
@@ -408,7 +144,7 @@ type SchemaChange = "none" | "annotations" | "contract";
  *
  * @public
  */
-declare class DocumentDiff {
+export declare class DocumentDiff {
   private constructor();
   /**
    * Classify the difference between two emitted document values (the
@@ -448,7 +184,7 @@ declare class DocumentDiff {
  *
  * @public
  */
-declare const DRAFT_07_META_SCHEMA = "http://json-schema.org/draft-07/schema#";
+export declare const DRAFT_07_META_SCHEMA = "http://json-schema.org/draft-07/schema#";
 declare const SchemaConversionError_base: Schema.Class<SchemaConversionError, Schema.TaggedStruct<"SchemaConversionError", {
   /** The `$id` of the document that failed to build. */
   readonly $id: Schema.String;
@@ -465,7 +201,34 @@ declare const SchemaConversionError_base: Schema.Class<SchemaConversionError, Sc
  *
  * @public
  */
-declare class SchemaConversionError extends SchemaConversionError_base {
+export declare class SchemaConversionError extends SchemaConversionError_base {
+  get message(): string;
+}
+declare const UndeclaredAnnotationKeyError_base: Schema.Class<UndeclaredAnnotationKeyError, Schema.TaggedStruct<"UndeclaredAnnotationKeyError", {
+  /** The `$id` of the document that was being built. */
+  readonly $id: Schema.String;
+  /** The offending keys, deduplicated and sorted. */
+  readonly keys: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+export declare class UndeclaredAnnotationKeyError extends UndeclaredAnnotationKeyError_base {
   get message(): string;
 }
 /**
@@ -482,14 +245,17 @@ interface StoreDocumentOptions {
    * `includeAnnotationKey`).
    *
    * The declared non-standard keyword families ({@link KeywordFamilies})
-   * are **always admitted** and carried into the built document — annotate
-   * a schema node (`Schema.String.annotate({ "x-taplo": ... })`) and the
-   * key survives the Draft-07 lowering via the post-lowering re-graft
-   * ({@link AnnotationCarriers}). A supplied `includeAnnotationKey` is
-   * consulted *in addition* for other keys; know the boundary: keys it
-   * admits outside the declared families reach the Draft 2020-12 document
-   * but are **dropped by the Draft-07 lowering** (its keyword walk copies
-   * a fixed subset) — verified against the installed beta.
+   * are **always admitted**, regardless of what a supplied
+   * `includeAnnotationKey` answers — annotate a schema node
+   * (`Schema.String.annotate({ "x-taplo": ... })`) and the key appears in
+   * the built document, in place, on the node it was attached to.
+   *
+   * A supplied `includeAnnotationKey` is consulted only for other keys,
+   * and **admitting one fails the build** with
+   * {@link UndeclaredAnnotationKeyError}. The families are the entire
+   * non-standard surface this package will emit, so the predicate has no
+   * admitting role left; it survives only because the rest of
+   * `ToJsonSchemaOptions` passes through, and is best left unset.
    */
   readonly jsonSchema?: Schema.ToJsonSchemaOptions;
 }
@@ -513,13 +279,21 @@ declare const StoreDocument_base: Schema.Class<StoreDocument, Schema.Struct<{
  * `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
  */
-declare class StoreDocument extends StoreDocument_base {
+export declare class StoreDocument extends StoreDocument_base {
   /**
    * Builds a Draft-07 document from its parts, filling `$schema` with
    * {@link DRAFT_07_META_SCHEMA}.
@@ -552,26 +326,475 @@ declare class StoreDocument extends StoreDocument_base {
    * synchronous — the primitive form; {@link StoreDocument.fromSchema} is
    * the same pipeline behind a span.
    */
-  static fromSchemaResult(source: Schema.Constraint, options: StoreDocumentOptions): Result.Result<StoreDocument, SchemaConversionError>;
+  static fromSchemaResult(source: Schema.Constraint, options: StoreDocumentOptions): Result.Result<StoreDocument, SchemaConversionError | UndeclaredAnnotationKeyError>;
   /**
    * Effect form of {@link StoreDocument.fromSchemaResult}, adding only the
    * `StoreDocument.fromSchema` span. Defined in terms of the `Result`
    * primitive — synchronous callers can use that variant directly.
    */
-  static readonly fromSchema: (source: Schema.Constraint, options: StoreDocumentOptions) => Effect.Effect<StoreDocument, SchemaConversionError, never>;
+  static readonly fromSchema: (source: Schema.Constraint, options: StoreDocumentOptions) => Effect.Effect<StoreDocument, SchemaConversionError | UndeclaredAnnotationKeyError, never>;
   /**
    * The flat SchemaStore publication shape: `$schema`, `$id`, the root
    * schema's keywords spread at the top level, then the `$defs` pool.
    * `$defs` is omitted when the pool is empty (a deliberate divergence
    * from the extraction source, which always emitted the key).
    */
-  toJson(): Record<string, unknown>;
+  toJson(): Record<string, unknown>;
+  /**
+   * Canonical JSON text of {@link StoreDocument.toJson}, via
+   * {@link CanonicalJson.serializeResult} — one serializer, so the
+   * document and any consumer-serialized value cannot drift.
+   */
+  serializeResult(options?: CanonicalJsonOptions): Result.Result<string, CanonicalJsonError>;
+}
+//#endregion
+//#region src/SchemaFile.d.ts
+declare const SchemaFileReadError_base: Schema.Class<SchemaFileReadError, Schema.TaggedStruct<"SchemaFileReadError", {
+  /** The path that could not be read. */
+  readonly path: Schema.String;
+  /** The underlying filesystem failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a schema file could not be read from the filesystem (a
+ * filesystem error other than not-found).
+ *
+ * @public
+ */
+export declare class SchemaFileReadError extends SchemaFileReadError_base {
+  get message(): string;
+}
+declare const SchemaFileNotFoundError_base: Schema.Class<SchemaFileNotFoundError, Schema.TaggedStruct<"SchemaFileNotFoundError", {
+  /** The path where the schema file was expected. */
+  readonly path: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that no schema file exists at the expected path. Carries its
+ * own tag for `catchTag` routing.
+ *
+ * @public
+ */
+export declare class SchemaFileNotFoundError extends SchemaFileNotFoundError_base {
+  get message(): string;
+}
+declare const SchemaFileWriteError_base: Schema.Class<SchemaFileWriteError, Schema.TaggedStruct<"SchemaFileWriteError", {
+  /** The path that could not be written. */
+  readonly path: Schema.String;
+  /** The underlying filesystem failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a schema file could not be written to the filesystem.
+ * Narrowed to the filesystem failure only — a serialization failure
+ * surfaces as its own `CanonicalJsonError`, never wrapped here.
+ *
+ * @public
+ */
+export declare class SchemaFileWriteError extends SchemaFileWriteError_base {
+  get message(): string;
+}
+/**
+ * What {@link SchemaFileShape.write} did to the filesystem: `"written"`
+ * when it wrote, `"unchanged"` when it left the file alone — reported as a
+ * value so the caller decides what to surface, never a log.
+ *
+ * @public
+ */
+type WriteOutcome = "written" | "unchanged";
+/**
+ * How the document being written relates to what was already on disk:
+ * {@link SchemaChange} plus `"created"` for a file that did not exist, so
+ * there was nothing to compare against.
+ *
+ * @public
+ */
+type WriteChange = SchemaChange | "created";
+/**
+ * The result of {@link SchemaFileShape.write}: what happened to the file,
+ * and what the difference MEANT.
+ *
+ * The two are independent on purpose. `change` answers the versioning
+ * question — `"annotations"` means only prose and editor affordances moved,
+ * so the document replaces its predecessor transparently and needs no new
+ * {@link SchemaVersioning} version, while `"contract"` means an assertion
+ * keyword moved and a consumer's document valid yesterday may be invalid
+ * today. `outcome` answers only whether bytes were written, which under
+ * `compare: "bytes"` can be `"written"` even when `change` is `"none"`.
+ *
+ * @public
+ */
+interface WriteResult {
+  /**
+   * Whether the file was written. **This is the authoritative answer to
+   * "did the filesystem get touched"** — always, under either `compare`
+   * mode. Do not infer it from `change`: under `compare: "bytes"` a
+   * `change` of `"none"` still writes.
+   */
+  readonly outcome: WriteOutcome;
+  /** What differs between the previous content and the new document. */
+  readonly change: WriteChange;
+}
+/**
+ * The result of {@link SchemaFileShape.check}: the same two answers
+ * {@link WriteResult} carries, for a call that touched nothing.
+ *
+ * `wouldWrite` is `outcome`'s counterpart — it honors `compare`, so it
+ * answers "would `write` do anything with these same options", which
+ * `change` alone cannot under `compare: "bytes"`.
+ *
+ * @public
+ */
+interface CheckResult {
+  /** Whether a `write` with the same options would touch the file. */
+  readonly wouldWrite: boolean;
+  /** What differs between the on-disk content and the new document. */
+  readonly change: WriteChange;
+}
+/**
+ * Options for {@link SchemaFileShape.write} and
+ * {@link SchemaFileShape.check}: the {@link CanonicalJsonOptions} the
+ * document serializes under, plus how `write` decides whether to touch the
+ * file.
+ *
+ * @public
+ */
+interface SchemaWriteOptions extends CanonicalJsonOptions {
+  /**
+   * How `write` decides the file needs rewriting:
+   *
+   * - `"value"` (the default) — compare the parsed content. Immune to any
+   *   other tool that reformats the file, which is the common case: a repo
+   *   whose pre-commit hook runs Biome or Prettier over `*.json` would
+   *   otherwise see every run rewrite the file forever, because the
+   *   formatter's bytes never match `CanonicalJson`'s.
+   * - `"bytes"` — compare the exact text, so the file on disk is only ever
+   *   `CanonicalJson`'s own output. Choose this when the emitted bytes are
+   *   themselves the artifact and no other tool is allowed to touch them.
+   *
+   * `change` in the {@link WriteResult} is classified by content either
+   * way; this option decides only whether a byte-level difference is
+   * enough to rewrite.
+   */
+  readonly compare?: "bytes" | "value";
+}
+/**
+ * The shape of the {@link SchemaFile} service — the value produced by
+ * {@link SchemaFile.make} and carried by its layer.
+ *
+ * @public
+ */
+interface SchemaFileShape {
+  /**
+   * Read a schema file's exact text (the drift-test read side: compare it
+   * against `StoreDocument.serializeResult`). Fails with
+   * `SchemaFileNotFoundError` (ENOENT) or `SchemaFileReadError` (other
+   * filesystem errors).
+   */
+  readonly read: (path: string) => Effect.Effect<string, SchemaFileReadError | SchemaFileNotFoundError>;
+  /**
+   * Serialize a document to canonical JSON and write it **only if the
+   * on-disk content differs** (a missing file counts as different),
+   * creating parent directories as needed. Answers a {@link WriteResult}
+   * as a value: what happened to the file, and what the difference meant.
+   * Fails with a `CanonicalJsonError` (the document does not serialize),
+   * `SchemaFileReadError` (the existing content could not be read for
+   * comparison) or `SchemaFileWriteError` (the filesystem write failed).
+   */
+  readonly write: (path: string, document: StoreDocument, options?: SchemaWriteOptions) => Effect.Effect<WriteResult, CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError>;
+  /**
+   * The same comparison {@link SchemaFileShape.write} makes, **without
+   * touching the filesystem** — the drift-check half of the pair, for a
+   * CI job that must assert a committed schema is current rather than
+   * regenerate it.
+   *
+   * Answers both questions the writer answers: `change` classifies the
+   * content (immune to a formatter having reflowed the committed file),
+   * and `wouldWrite` honors `compare`, so it agrees with `write` under
+   * either mode. Checking drift is `change`; predicting the writer is
+   * `wouldWrite`.
+   */
+  readonly check: (path: string, document: StoreDocument, options?: SchemaWriteOptions) => Effect.Effect<CheckResult, CanonicalJsonError | SchemaFileReadError>;
+}
+declare const SchemaFile_base: Context.ServiceClass<SchemaFile, "@effected/schemastore/SchemaFile", SchemaFileShape>;
+/**
+ * Reads and writes emitted schema documents over core `FileSystem` /
+ * `Path` — the package's one IO surface. The layer requires those
+ * services; provide `@effect/platform-node`'s `NodeFileSystem` / `NodePath`
+ * (or a bun equivalent) at the application boundary.
+ *
+ * `write` is write-if-changed, and by default compares **content**: an
+ * unchanged document never touches the file even if another tool has
+ * reformatted it, so a generator committed to a repo whose pre-commit hook
+ * formats JSON does not churn on every run. It also reports what the
+ * difference meant — `"annotations"` (prose only, replaces its predecessor
+ * transparently) versus `"contract"` (an assertion moved, so a new
+ * `SchemaVersioning` version is warranted). `check` makes the same
+ * comparison without writing, which is what a CI drift job wants.
+ *
+ * @example
+ * ```ts
+ * import { SchemaFile, StoreDocument } from "@effected/schemastore";
+ * import { NodeFileSystem, NodePath } from "@effect/platform-node";
+ * import { Effect, Layer, Schema } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const files = yield* SchemaFile;
+ *   const document = yield* StoreDocument.fromSchema(Schema.Struct({ name: Schema.String }), {
+ *     $id: "https://example.com/config.schema.json",
+ *   });
+ *   return yield* files.write("schemas/config.schema.json", document);
+ * }).pipe(
+ *   Effect.provide(SchemaFile.layer),
+ *   Effect.provide(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer)),
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare class SchemaFile extends SchemaFile_base {
+  /** Build the service implementation from `FileSystem` / `Path` in context; use {@link SchemaFile.layer} to provide it. */
+  static readonly make: Effect.Effect<SchemaFileShape, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The live layer. Requires core `FileSystem` / `Path`, provided by the
+   * consumer's platform implementation at the edge.
+   */
+  static readonly layer: Layer.Layer<SchemaFile, never, FileSystem.FileSystem | Path.Path>;
+}
+//#endregion
+//#region src/SchemaVersioning.d.ts
+declare const InvalidSchemaVersionError_base: Schema.Class<InvalidSchemaVersionError, Schema.TaggedStruct<"InvalidSchemaVersionError", {
+  /** The raw input string that failed to parse. */
+  readonly input: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a string is not a valid SchemaStore version label.
+ *
+ * Raised by {@link SchemaVersioning.parse}.
+ *
+ * @public
+ */
+export declare class InvalidSchemaVersionError extends InvalidSchemaVersionError_base {
+  get message(): string;
+}
+/**
+ * A schema version label: a branded string holding a **full three-component
+ * SemVer** — `major.minor.patch` with an optional prerelease, validated by
+ * `@effected/semver` itself. Build metadata is rejected (see below).
+ *
+ * `1.2` and `1` are NOT accepted, though SchemaStore's own corpus uses such
+ * labels: requiring all three components makes a label unambiguous to split
+ * back out of `<name>-<version>.json` or its URL, which is what consumers
+ * do with it. The file-name convention around the label stays SchemaStore's.
+ *
+ * The label round-trips verbatim into file names and catalog `versions`
+ * keys; ordering parses it directly (see {@link SchemaVersioning.Order}).
+ *
+ * @public
+ */
+export declare const SchemaVersion: Schema.brand<Schema.String, "SchemaVersion">;
+/**
+ * The type of a validated SchemaStore version label.
+ *
+ * @public
+ */
+export type SchemaVersion = typeof SchemaVersion.Type;
+/**
+ * The `url`/`versions` half of a catalog entry, as assembled by
+ * {@link SchemaVersioning.catalogUrls}.
+ *
+ * @public
+ */
+interface CatalogUrls {
+  /** The catalog `url` — the unversioned file, or the latest versioned file. */
+  readonly url: string;
+  /**
+   * The versioned catalog's `versions` map (label → url), inserted — and,
+   * since a three-component label can never be integer-like, enumerated
+   * and serialized — in ascending version order.
+   */
+  readonly versions?: Readonly<Record<string, string>>;
+}
+/**
+ * Both SchemaStore catalog modes as pure derivations: unversioned (a plain
+ * `name.json` file, `url` only) and versioned (`name-<version>.json` files
+ * — SchemaStore's own suffix convention — a `versions` map, and `url`
+ * pointing at the latest version).
+ *
+ * Version labels are full three-component SemVer, so ordering is plain
+ * SemVer precedence: `1.10.0` above `1.9.0`, `2.0.0-beta` below `2.0.0`.
+ *
+ * @public
+ */
+export declare class SchemaVersioning {
+  private constructor();
+  /**
+   * Parses a version label. Pure and synchronous — the primitive form;
+   * {@link SchemaVersioning.parse} is the same check behind a span.
+   */
+  static parseResult(input: string): Result.Result<SchemaVersion, InvalidSchemaVersionError>;
+  /**
+   * Effect form of {@link SchemaVersioning.parseResult}, adding only the
+   * `SchemaVersioning.parse` span. Defined in terms of the `Result`
+   * primitive — synchronous callers can use that variant directly.
+   */
+  static readonly parse: (input: string) => Effect.Effect<string & import("effect/Brand").Brand<"SchemaVersion">, InvalidSchemaVersionError, never>;
+  /**
+   * `Order` instance over version labels: plain SemVer precedence.
+   * `1.10.0` sorts above `1.9.0` (numeric, not lexical) and `2.0.0-beta`
+   * below `2.0.0` (prerelease precedence).
+   */
+  static readonly Order: Order.Order<SchemaVersion>;
+  /**
+   * The highest version label by {@link SchemaVersioning.Order}, or
+   * `Option.none()` for an empty collection.
+   */
+  static latest(versions: ReadonlyArray<SchemaVersion>): Option.Option<SchemaVersion>;
+  /**
+   * 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: SchemaVersion): boolean;
+  /**
+   * 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: SchemaVersion, change: WriteChange): SchemaVersion;
+  /**
+   * Derives the schema file name for a catalog name: `name.json`
+   * unversioned, `name-<version>.json` versioned.
+   *
+   * The name must be a simple file base name (no separators, no
+   * whitespace); anything else is a wiring mistake and throws.
+   */
+  static fileName(name: string, version?: SchemaVersion): string;
+  /**
+   * The canonical URL a schema file is hosted at: `baseUrl` joined with
+   * {@link SchemaVersioning.fileName}.
+   */
+  static schemaUrl(baseUrl: string, name: string, version?: SchemaVersion): string;
+  /**
+   * Assembles the `url`/`versions` half of a catalog entry.
+   *
+   * Omitting `versions` selects the unversioned mode (`url` only,
+   * pointing at the plain `name.json`). Providing them selects the
+   * versioned mode: the `versions` map carries every label, and `url`
+   * points at the latest version's file. An **empty** `versions` array is
+   * a contradiction (versioned mode with no versions) and throws — pass
+   * `undefined` for the unversioned mode.
+   *
+   * Labels are inserted in ascending {@link SchemaVersioning.Order} and
+   * stay that way on serialization. Requiring three components is what
+   * buys this: JavaScript enumerates array-index-like keys first, so the
+   * old grammar's bare-major label (`"2"`) jumped ahead of every dotted
+   * one regardless of insertion order. No SemVer label is integer-like,
+   * so that hazard is gone. Deriving ordering from the labels themselves
+   * (as {@link SchemaVersioning.latest} does) is still the robust read.
+   */
+  static catalogUrls(options: {
+    readonly baseUrl: string;
+    readonly name: string;
+    readonly versions?: ReadonlyArray<SchemaVersion>;
+  }): CatalogUrls;
+}
+//#endregion
+//#region src/CatalogEntry.d.ts
+declare const CatalogLintFinding_base: Schema.Class<CatalogLintFinding, Schema.Struct<{
+  /** Which hygiene check fired. */
+  readonly check: Schema.Literals<readonly ["GenericFileMatch", "ComplexFileMatch"]>;
+  /** The `fileMatch` pattern the finding is about. */
+  readonly pattern: Schema.String;
+  /** Human-readable explanation with the SchemaStore rationale. */
+  readonly message: Schema.String;
+}>, {}>;
+/**
+ * A fileMatch hygiene finding: a value in a lint report, not an error —
+ * SchemaStore reviewers reject entries over these, so surfacing them
+ * locally is the point, but a warned entry is still a valid entry.
+ *
+ * @public
+ */
+export declare class CatalogLintFinding extends CatalogLintFinding_base {}
+declare const CatalogEntry_base: Schema.Class<CatalogEntry, Schema.Struct<{
+  /** The schema's display name in the catalog. */
+  readonly name: Schema.String;
+  /** The catalog description. */
+  readonly description: Schema.String;
+  /** Glob patterns editors match files against. */
+  readonly fileMatch: Schema.$Array<Schema.String>;
+  /** The schema URL — the unversioned file, or the latest version. */
+  readonly url: Schema.String;
+  /**
+   * Versioned mode only: label → schema URL. Inserted ascending, but key
+   * order is not a contract — bare-major labels enumerate first (see
+   * `SchemaVersioning.catalogUrls`); derive ordering from the labels.
+   */
+  readonly versions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+}>, {}>;
+/**
+ * A SchemaStore `catalog.json` entry: the class is the schema, so decoding
+ * an existing entry and encoding one for submission are the same artifact.
+ * `versions` is present only for versioned catalogs
+ * ({@link SchemaVersioning.catalogUrls} assembles both modes).
+ *
+ * @public
+ */
+export declare class CatalogEntry extends CatalogEntry_base {
+  /**
+   * Assembles an entry from a catalog identity plus
+   * {@link SchemaVersioning.catalogUrls}' inputs: pass `versions` for the
+   * versioned mode (the `versions` map and latest-pointing `url` are
+   * derived), omit it for the unversioned mode.
+   */
+  static assemble(options: {
+    readonly name: string;
+    readonly description: string;
+    readonly fileMatch: ReadonlyArray<string>;
+    readonly baseUrl: string;
+    readonly fileBaseName?: string;
+    readonly versions?: ReadonlyArray<SchemaVersion>;
+  }): CatalogEntry;
+  /**
+   * The fileMatch hygiene lint over this entry's patterns — pure shape
+   * analysis (no glob engine): generic patterns SchemaStore rejects and
+   * complex constructs it asks contributors to expand.
+   */
+  lint(): ReadonlyArray<CatalogLintFinding>;
   /**
-   * Canonical JSON text of {@link StoreDocument.toJson}, via
-   * {@link CanonicalJson.serializeResult} — one serializer, so the
-   * document and any consumer-serialized value cannot drift.
+   * {@link CatalogEntry.lint} over a bare pattern list, for callers
+   * checking patterns before an entry exists.
    */
-  serializeResult(options?: CanonicalJsonOptions): Result.Result<string, CanonicalJsonError>;
+  static lintFileMatch(patterns: ReadonlyArray<string>): ReadonlyArray<CatalogLintFinding>;
 }
 //#endregion
 //#region src/DocumentLint.d.ts
@@ -592,7 +815,7 @@ declare const DocumentLintFinding_base: Schema.Class<DocumentLintFinding, Schema
  *
  * @public
  */
-declare class DocumentLintFinding extends DocumentLintFinding_base {}
+export declare class DocumentLintFinding extends DocumentLintFinding_base {}
 /**
  * Owned structural checks over an assembled {@link StoreDocument} — the
  * always-available half of the validation story (a real-engine gate like
@@ -603,7 +826,7 @@ declare class DocumentLintFinding extends DocumentLintFinding_base {}
  *   `#/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.
  *
@@ -612,7 +835,7 @@ declare class DocumentLintFinding extends DocumentLintFinding_base {}
  *
  * @public
  */
-declare class DocumentLint {
+export declare class DocumentLint {
   private constructor();
   /**
    * Runs every check; total — hostile nesting degrades to a
@@ -623,10 +846,12 @@ declare class DocumentLint {
 //#endregion
 //#region src/KeywordFamilies.d.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`,
@@ -639,241 +864,67 @@ declare class DocumentLint {
  * - **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.
  */
 /**
  * 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
  */
-declare class KeywordFamilies {
+export declare class KeywordFamilies {
   private constructor();
   /**
    * 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: string): boolean;
 }
 //#endregion
-//#region src/SchemaFile.d.ts
-declare const SchemaFileReadError_base: Schema.Class<SchemaFileReadError, Schema.TaggedStruct<"SchemaFileReadError", {
-  /** The path that could not be read. */
-  readonly path: Schema.String;
-  /** The underlying filesystem failure, preserved structurally. */
-  readonly cause: Schema.Defect;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Indicates that a schema file could not be read from the filesystem (a
- * filesystem error other than not-found).
- *
- * @public
- */
-declare class SchemaFileReadError extends SchemaFileReadError_base {
-  get message(): string;
-}
-declare const SchemaFileNotFoundError_base: Schema.Class<SchemaFileNotFoundError, Schema.TaggedStruct<"SchemaFileNotFoundError", {
-  /** The path where the schema file was expected. */
-  readonly path: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Indicates that no schema file exists at the expected path. Carries its
- * own tag for `catchTag` routing.
- *
- * @public
- */
-declare class SchemaFileNotFoundError extends SchemaFileNotFoundError_base {
-  get message(): string;
-}
-declare const SchemaFileWriteError_base: Schema.Class<SchemaFileWriteError, Schema.TaggedStruct<"SchemaFileWriteError", {
-  /** The path that could not be written. */
-  readonly path: Schema.String;
-  /** The underlying filesystem failure, preserved structurally. */
-  readonly cause: Schema.Defect;
-}>, import("effect/Cause").YieldableError>;
-/**
- * Indicates that a schema file could not be written to the filesystem.
- * Narrowed to the filesystem failure only — a serialization failure
- * surfaces as its own `CanonicalJsonError`, never wrapped here.
- *
- * @public
- */
-declare class SchemaFileWriteError extends SchemaFileWriteError_base {
-  get message(): string;
-}
-/**
- * What {@link SchemaFileShape.write} did to the filesystem: `"written"`
- * when it wrote, `"unchanged"` when it left the file alone — reported as a
- * value so the caller decides what to surface, never a log.
- *
- * @public
- */
-type WriteOutcome = "written" | "unchanged";
-/**
- * How the document being written relates to what was already on disk:
- * {@link SchemaChange} plus `"created"` for a file that did not exist, so
- * there was nothing to compare against.
- *
- * @public
- */
-type WriteChange = SchemaChange | "created";
-/**
- * The result of {@link SchemaFileShape.write}: what happened to the file,
- * and what the difference MEANT.
- *
- * The two are independent on purpose. `change` answers the versioning
- * question — `"annotations"` means only prose and editor affordances moved,
- * so the document replaces its predecessor transparently and needs no new
- * {@link SchemaVersioning} version, while `"contract"` means an assertion
- * keyword moved and a consumer's document valid yesterday may be invalid
- * today. `outcome` answers only whether bytes were written, which under
- * `compare: "bytes"` can be `"written"` even when `change` is `"none"`.
- *
- * @public
- */
-interface WriteResult {
-  /**
-   * Whether the file was written. **This is the authoritative answer to
-   * "did the filesystem get touched"** — always, under either `compare`
-   * mode. Do not infer it from `change`: under `compare: "bytes"` a
-   * `change` of `"none"` still writes.
-   */
-  readonly outcome: WriteOutcome;
-  /** What differs between the previous content and the new document. */
-  readonly change: WriteChange;
-}
-/**
- * The result of {@link SchemaFileShape.check}: the same two answers
- * {@link WriteResult} carries, for a call that touched nothing.
- *
- * `wouldWrite` is `outcome`'s counterpart — it honors `compare`, so it
- * answers "would `write` do anything with these same options", which
- * `change` alone cannot under `compare: "bytes"`.
- *
- * @public
- */
-interface CheckResult {
-  /** Whether a `write` with the same options would touch the file. */
-  readonly wouldWrite: boolean;
-  /** What differs between the on-disk content and the new document. */
-  readonly change: WriteChange;
-}
-/**
- * Options for {@link SchemaFileShape.write} and
- * {@link SchemaFileShape.check}: the {@link CanonicalJsonOptions} the
- * document serializes under, plus how `write` decides whether to touch the
- * file.
- *
- * @public
- */
-interface SchemaWriteOptions extends CanonicalJsonOptions {
-  /**
-   * How `write` decides the file needs rewriting:
-   *
-   * - `"value"` (the default) — compare the parsed content. Immune to any
-   *   other tool that reformats the file, which is the common case: a repo
-   *   whose pre-commit hook runs Biome or Prettier over `*.json` would
-   *   otherwise see every run rewrite the file forever, because the
-   *   formatter's bytes never match `CanonicalJson`'s.
-   * - `"bytes"` — compare the exact text, so the file on disk is only ever
-   *   `CanonicalJson`'s own output. Choose this when the emitted bytes are
-   *   themselves the artifact and no other tool is allowed to touch them.
-   *
-   * `change` in the {@link WriteResult} is classified by content either
-   * way; this option decides only whether a byte-level difference is
-   * enough to rewrite.
-   */
-  readonly compare?: "bytes" | "value";
-}
-/**
- * The shape of the {@link SchemaFile} service — the value produced by
- * {@link SchemaFile.make} and carried by its layer.
- *
- * @public
- */
-interface SchemaFileShape {
-  /**
-   * Read a schema file's exact text (the drift-test read side: compare it
-   * against `StoreDocument.serializeResult`). Fails with
-   * `SchemaFileNotFoundError` (ENOENT) or `SchemaFileReadError` (other
-   * filesystem errors).
-   */
-  readonly read: (path: string) => Effect.Effect<string, SchemaFileReadError | SchemaFileNotFoundError>;
-  /**
-   * Serialize a document to canonical JSON and write it **only if the
-   * on-disk content differs** (a missing file counts as different),
-   * creating parent directories as needed. Answers a {@link WriteResult}
-   * as a value: what happened to the file, and what the difference meant.
-   * Fails with a `CanonicalJsonError` (the document does not serialize),
-   * `SchemaFileReadError` (the existing content could not be read for
-   * comparison) or `SchemaFileWriteError` (the filesystem write failed).
-   */
-  readonly write: (path: string, document: StoreDocument, options?: SchemaWriteOptions) => Effect.Effect<WriteResult, CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError>;
-  /**
-   * The same comparison {@link SchemaFileShape.write} makes, **without
-   * touching the filesystem** — the drift-check half of the pair, for a
-   * CI job that must assert a committed schema is current rather than
-   * regenerate it.
-   *
-   * Answers both questions the writer answers: `change` classifies the
-   * content (immune to a formatter having reflowed the committed file),
-   * and `wouldWrite` honors `compare`, so it agrees with `write` under
-   * either mode. Checking drift is `change`; predicting the writer is
-   * `wouldWrite`.
-   */
-  readonly check: (path: string, document: StoreDocument, options?: SchemaWriteOptions) => Effect.Effect<CheckResult, CanonicalJsonError | SchemaFileReadError>;
-}
-declare const SchemaFile_base: Context.ServiceClass<SchemaFile, "@effected/schemastore/SchemaFile", SchemaFileShape>;
-/**
- * Reads and writes emitted schema documents over core `FileSystem` /
- * `Path` — the package's one IO surface. The layer requires those
- * services; provide `@effect/platform-node`'s `NodeFileSystem` / `NodePath`
- * (or a bun equivalent) at the application boundary.
- *
- * `write` is write-if-changed, and by default compares **content**: an
- * unchanged document never touches the file even if another tool has
- * reformatted it, so a generator committed to a repo whose pre-commit hook
- * formats JSON does not churn on every run. It also reports what the
- * difference meant — `"annotations"` (prose only, replaces its predecessor
- * transparently) versus `"contract"` (an assertion moved, so a new
- * `SchemaVersioning` version is warranted). `check` makes the same
- * comparison without writing, which is what a CI drift job wants.
- *
- * @example
- * ```ts
- * import { SchemaFile, StoreDocument } from "@effected/schemastore";
- * import { NodeFileSystem, NodePath } from "@effect/platform-node";
- * import { Effect, Layer, Schema } from "effect";
- *
- * const program = Effect.gen(function* () {
- *   const files = yield* SchemaFile;
- *   const document = yield* StoreDocument.fromSchema(Schema.Struct({ name: Schema.String }), {
- *     $id: "https://example.com/config.schema.json",
- *   });
- *   return yield* files.write("schemas/config.schema.json", document);
- * }).pipe(
- *   Effect.provide(SchemaFile.layer),
- *   Effect.provide(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer)),
- * );
- * ```
- *
- * @public
- */
-declare class SchemaFile extends SchemaFile_base {
-  /** Build the service implementation from `FileSystem` / `Path` in context; use {@link SchemaFile.layer} to provide it. */
-  static readonly make: Effect.Effect<SchemaFileShape, never, FileSystem.FileSystem | Path.Path>;
-  /**
-   * The live layer. Requires core `FileSystem` / `Path`, provided by the
-   * consumer's platform implementation at the edge.
-   */
-  static readonly layer: Layer.Layer<SchemaFile, never, FileSystem.FileSystem | Path.Path>;
-}
-//#endregion
 //#region src/SchemaTarget.d.ts
 /**
  * A single schema publication target: an Effect Schema source paired with
@@ -886,7 +937,7 @@ declare class SchemaFile extends SchemaFile_base {
  *
  * @public
  */
-interface SchemaTarget {
+export interface SchemaTarget {
   /** The Effect Schema source the document is generated from. */
   readonly schema: Schema.Constraint;
   /** The canonical `$id` URL the generated document declares. */
@@ -903,7 +954,20 @@ interface SchemaTarget {
   readonly name?: string;
   /** The destination path the document is written to (`SchemaFile`). */
   readonly path: string;
-  /** The version label, for versioned catalog mode. Omit for unversioned. */
+  /**
+   * The version label, for versioned catalog mode. Omit for unversioned.
+   *
+   * It carries a second meaning the catalog does not: presence of a
+   * **pinned** label (one with no prerelease) declares that consumers pin
+   * this document's URL, so `SchemaPipeline.run` refuses to rewrite it in
+   * place when its validation contract changes — bump `version`, `$id` and
+   * `path` together instead, or pass `contractChanges: "allow"`. That is
+   * only coherent when the version participates in `path`
+   * (`schemas/<version>/<name>-<version>.json`): a versioned target at a
+   * fixed path compares the same file forever, and bumping `version` does
+   * not move it. A prerelease label declares its own instability and is
+   * rewritten in place.
+   */
   readonly version?: SchemaVersion;
 }
 /**
@@ -911,7 +975,7 @@ interface SchemaTarget {
  *
  * @public
  */
-declare class SchemaTarget {
+export declare class SchemaTarget {
   private constructor();
   /**
    * Builds an unversioned target. `name` is optional — only catalog
@@ -954,7 +1018,7 @@ declare const SchemaValidatorError_base: Schema.Class<SchemaValidatorError, Sche
  *
  * @public
  */
-declare class SchemaValidatorError extends SchemaValidatorError_base {
+export declare class SchemaValidatorError extends SchemaValidatorError_base {
   get message(): string;
 }
 declare const ValidationFinding_base: Schema.Class<ValidationFinding, Schema.Struct<{
@@ -972,7 +1036,7 @@ declare const ValidationFinding_base: Schema.Class<ValidationFinding, Schema.Str
  *
  * @public
  */
-declare class ValidationFinding extends ValidationFinding_base {}
+export declare class ValidationFinding extends ValidationFinding_base {}
 /**
  * Options for {@link SchemaValidatorShape.validate}.
  *
@@ -1038,16 +1102,19 @@ declare const SchemaValidator_base: Context.ServiceClass<SchemaValidator, "@effe
  *
  * @public
  */
-declare class SchemaValidator extends SchemaValidator_base {
+export declare class SchemaValidator extends SchemaValidator_base {
   /**
    * The shipped ajv implementation — the default a consumer provides.
    *
    * `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.
@@ -1094,7 +1161,7 @@ declare const PipelineFinding_base: Schema.Class<PipelineFinding, Schema.Struct<
  *
  * @public
  */
-declare class PipelineFinding extends PipelineFinding_base {
+export declare class PipelineFinding extends PipelineFinding_base {
   /**
    * What to call this finding when rendering it: the check name when the
    * gate named one, the gate itself otherwise.
@@ -1118,7 +1185,64 @@ declare const SchemaGateError_base: Schema.Class<SchemaGateError, Schema.TaggedS
  *
  * @public
  */
-declare class SchemaGateError extends SchemaGateError_base {
+export declare class SchemaGateError extends SchemaGateError_base {
+  get message(): string;
+}
+/**
+ * How {@link SchemaPipeline.run} treats a target whose document would change
+ * its validation contract.
+ *
+ * - `"block-versioned"` (the default) — a target carrying a PINNED `version`
+ *   ({@link SchemaVersioning.isPinned}) is a published, URL-pinned document:
+ *   a `"contract"` change fails with {@link SchemaContractChangeError} BEFORE
+ *   any write. A target with no `version`, or with a prerelease label, is a
+ *   document that replaces its predecessor in place and is rewritten as
+ *   before.
+ * - `"allow"` — classify and report only, never refuse: the pre-guard
+ *   behaviour. Also the sanctioned REPAIR path for a published file whose
+ *   text no longer parses — `SchemaFile` classifies unparseable text as
+ *   `"contract"` so it stays regenerable, and under the default that
+ *   classification is refused.
+ *
+ * The policy reads `change`, which is content-classified under either
+ * `write.compare` mode, so `"bytes"` neither strengthens nor weakens it.
+ *
+ * The policy is only coherent when the version participates in `path`
+ * (`schemas/<version>/<name>-<version>.json`): a versioned target at a fixed
+ * path compares the same file forever, and bumping `version` does not move
+ * it.
+ *
+ * @public
+ */
+type ContractChangePolicy = "block-versioned" | "allow";
+declare const ContractChangeTarget_base: Schema.Class<ContractChangeTarget, Schema.Struct<{
+  /** The target's `$id`. */
+  readonly $id: Schema.String;
+  /** The path the document would have been written to. */
+  readonly path: Schema.String;
+  /** The target's pinned label. */
+  readonly version: Schema.brand<Schema.String, "SchemaVersion">;
+  /** The label to publish under instead — {@link SchemaVersioning.next} of `version`. */
+  readonly nextVersion: Schema.brand<Schema.String, "SchemaVersion">;
+}>, {}>;
+/**
+ * One published document whose validation contract would change.
+ *
+ * @public
+ */
+export declare class ContractChangeTarget extends ContractChangeTarget_base {}
+declare const SchemaContractChangeError_base: Schema.Class<SchemaContractChangeError, Schema.TaggedStruct<"SchemaContractChangeError", {
+  /** Every published target whose contract would change, in target order. */
+  readonly targets: Schema.$Array<typeof ContractChangeTarget>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+export declare class SchemaContractChangeError extends SchemaContractChangeError_base {
   get message(): string;
 }
 /**
@@ -1161,6 +1285,17 @@ interface PipelineCheckResult {
    * never mistaken for clean drift.
    */
   readonly blocked: boolean;
+  /**
+   * Whether the {@link ContractChangePolicy} would refuse this write.
+   *
+   * Read it side by side with {@link PipelineCheckResult.blocked}: `blocked`
+   * answers "would findings block a run under `blocking`", while
+   * `contractBlocked` answers "would the contract policy refuse this write
+   * under `contractChanges`". A drift test that reads `contractBlocked` can
+   * print the right remedy — "regenerate" is wrong advice for a target the
+   * generator will refuse; the fix is a version bump.
+   */
+  readonly contractBlocked: boolean;
   /** What differs between the on-disk content and the new document. */
   readonly change: WriteChange;
   /** Every finding, blocking or not. */
@@ -1185,16 +1320,25 @@ interface SchemaPipelineOptions {
    *
    * **Which findings can actually reach you here.** A `SchemaTarget`
    * carries a `Schema`, so the pipeline's documents come from
-   * `StoreDocument.fromSchema` — and the Draft-07 lowering drops every
-   * keyword outside its copy-list, so an undeclared keyword never
-   * survives to be linted. Through this entry point `UnknownKeyword` is
-   * therefore effectively unreachable, and **the engine gate is what
-   * blocks in practice**. The lint's warning checks earn their keep on
+   * `StoreDocument.fromSchema` — which never admits an undeclared
+   * keyword: the pipeline supplies no `includeAnnotationKey`, and one
+   * that admitted anything outside the declared families would fail the
+   * build. An undeclared keyword therefore never exists to be linted.
+   * Through this entry point `UnknownKeyword` is effectively unreachable,
+   * and **the engine gate is what blocks in practice**. The lint's warning checks earn their keep on
    * documents this pipeline did not build — a hand-assembled
    * `StoreDocument.draft07`, or one read back off disk — and on depth,
    * which a schema can genuinely exceed.
    */
   readonly blocking?: (finding: PipelineFinding) => boolean;
+  /**
+   * How {@link SchemaPipeline.run} treats a target whose document would
+   * change its validation contract. Defaults to `"block-versioned"`: a
+   * target carrying a pinned `version` is refused rather than rewritten in
+   * place. Pass `"allow"` to classify and report only — including to repair
+   * a published file whose on-disk text no longer parses.
+   */
+  readonly contractChanges?: ContractChangePolicy;
   /** Passed through to `SchemaValidator.validate`. */
   readonly validator?: SchemaValidatorOptions;
   /** Passed through to `SchemaFile.write` / `SchemaFile.check`. */
@@ -1233,17 +1377,49 @@ interface SchemaPipelineOptions {
  *
  * @public
  */
-declare class SchemaPipeline {
+export declare class SchemaPipeline {
   private 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.
    *
-   * 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.
+   * **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];
+   *
+   * 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: ReadonlyArray<SchemaTarget>, options?: SchemaPipelineOptions): Effect.Effect<ReadonlyArray<PipelineResult>, SchemaGateError | SchemaConversionError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError, SchemaFile | SchemaValidator>;
+  static run(targets: ReadonlyArray<SchemaTarget>, options?: SchemaPipelineOptions): Effect.Effect<ReadonlyArray<PipelineResult>, SchemaGateError | SchemaContractChangeError | SchemaConversionError | UndeclaredAnnotationKeyError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError, SchemaFile | SchemaValidator>;
   /**
    * The same walk with **no writes** — the drift-check counterpart, for a
    * CI job asserting the committed schemas are current.
@@ -1258,19 +1434,19 @@ declare class SchemaPipeline {
    * The error channel is left to the mechanisms that genuinely cannot
    * produce a report (generation, serialization, the engine, the read).
    */
-  static check(targets: ReadonlyArray<SchemaTarget>, options?: SchemaPipelineOptions): Effect.Effect<ReadonlyArray<PipelineCheckResult>, SchemaConversionError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError, SchemaFile | SchemaValidator>;
+  static check(targets: ReadonlyArray<SchemaTarget>, options?: SchemaPipelineOptions): Effect.Effect<ReadonlyArray<PipelineCheckResult>, SchemaConversionError | UndeclaredAnnotationKeyError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError, SchemaFile | SchemaValidator>;
   /**
    * {@link SchemaPipeline.run} for a single target, answering its one
    * result directly — so a caller with one target does not index into an
    * array and prove to the type system that element zero exists.
    */
-  static runOne(target: SchemaTarget, options?: SchemaPipelineOptions): Effect.Effect<PipelineResult, SchemaGateError | SchemaConversionError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError, SchemaFile | SchemaValidator>;
+  static runOne(target: SchemaTarget, options?: SchemaPipelineOptions): Effect.Effect<PipelineResult, SchemaGateError | SchemaContractChangeError | SchemaConversionError | UndeclaredAnnotationKeyError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError, SchemaFile | SchemaValidator>;
   /**
    * {@link SchemaPipeline.check} for a single target, answering its one
    * result directly.
    */
-  static checkOne(target: SchemaTarget, options?: SchemaPipelineOptions): Effect.Effect<PipelineCheckResult, SchemaConversionError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError, SchemaFile | SchemaValidator>;
+  static checkOne(target: SchemaTarget, options?: SchemaPipelineOptions): Effect.Effect<PipelineCheckResult, SchemaConversionError | UndeclaredAnnotationKeyError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError, SchemaFile | SchemaValidator>;
 }
 //#endregion
-export { AnnotationCarriers, CanonicalJson, type CanonicalJsonError, type CanonicalJsonOptions, CarrierDepthExceededError, CatalogEntry, CatalogLintFinding, type CatalogUrls, type CheckResult, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, type PipelineCheckResult, PipelineFinding, type PipelineResult, type SchemaChange, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, type SchemaFileShape, SchemaFileWriteError, SchemaGateError, SchemaPipeline, type SchemaPipelineOptions, SchemaTarget, SchemaValidator, SchemaValidatorError, type SchemaValidatorOptions, type SchemaValidatorShape, SchemaVersion, SchemaVersioning, type SchemaWriteOptions, StoreDocument, type StoreDocumentOptions, ValidationFinding, type WriteChange, type WriteOutcome, type WriteResult };
+export type { CanonicalJsonError, CanonicalJsonOptions, CatalogUrls, CheckResult, ContractChangePolicy, PipelineCheckResult, PipelineResult, SchemaChange, SchemaFileShape, SchemaPipelineOptions, SchemaValidatorOptions, SchemaValidatorShape, SchemaWriteOptions, StoreDocumentOptions, WriteChange, WriteOutcome, WriteResult };
 //# sourceMappingURL=index.d.ts.map