@effected/schemastore 0.4.0 → 0.5.0

package/index.d.ts

@@ -165,201 +165,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:
@@ -571,7 +376,456 @@ declare class StoreDocument extends StoreDocument_base {
    * {@link CanonicalJson.serializeResult} — one serializer, so the
    * document and any consumer-serialized value cannot drift.
    */
-  serializeResult(options?: CanonicalJsonOptions): Result.Result<string, CanonicalJsonError>;
+  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
+ */
+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/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>;
+  /**
+   * 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
+ */
+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/DocumentLint.d.ts
@@ -603,7 +857,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.
  *
@@ -623,10 +877,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,6 +895,43 @@ 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
@@ -647,7 +940,7 @@ declare class DocumentLint {
 /**
  * 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
  */
@@ -656,224 +949,12 @@ declare class KeywordFamilies {
   /**
    * 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
@@ -903,7 +984,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;
 }
 /**
@@ -1045,9 +1139,12 @@ declare class SchemaValidator extends SchemaValidator_base {
    * `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.
@@ -1121,6 +1218,63 @@ declare const SchemaGateError_base: Schema.Class<SchemaGateError, Schema.TaggedS
 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
+ */
+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
+ */
+declare class SchemaContractChangeError extends SchemaContractChangeError_base {
+  get message(): string;
+}
 /**
  * What the pipeline did with one target.
  *
@@ -1161,6 +1315,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. */
@@ -1195,6 +1360,14 @@ interface SchemaPipelineOptions {
    * 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`. */
@@ -1237,13 +1410,45 @@ 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 | 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.
@@ -1264,7 +1469,7 @@ declare class SchemaPipeline {
    * 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 | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError, SchemaFile | SchemaValidator>;
   /**
    * {@link SchemaPipeline.check} for a single target, answering its one
    * result directly.
@@ -1272,5 +1477,5 @@ declare class SchemaPipeline {
   static checkOne(target: SchemaTarget, options?: SchemaPipelineOptions): Effect.Effect<PipelineCheckResult, SchemaConversionError | 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 { AnnotationCarriers, CanonicalJson, type CanonicalJsonError, type CanonicalJsonOptions, CarrierDepthExceededError, CatalogEntry, CatalogLintFinding, type CatalogUrls, type CheckResult, type ContractChangePolicy, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, type PipelineCheckResult, PipelineFinding, type PipelineResult, type SchemaChange, SchemaContractChangeError, 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 };
 //# sourceMappingURL=index.d.ts.map