@effected/schemastore 0.1.2 → 0.2.0

package/index.d.ts

@@ -181,11 +181,17 @@ declare class InvalidSchemaVersionError extends InvalidSchemaVersionError_base {
   get message(): string;
 }
 /**
- * A SchemaStore version label: a branded string validated against the
- * catalog's version grammar (`major[.minor[.patch]][-prerelease]`). The
- * label round-trips verbatim into file names and catalog `versions` keys;
- * ordering pads it to a full SemVer internally (see
- * {@link SchemaVersioning.Order}).
+ * 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
  */
@@ -206,23 +212,20 @@ interface CatalogUrls {
   /** The catalog `url` — the unversioned file, or the latest versioned file. */
   readonly url: string;
   /**
-   * The versioned catalog's `versions` map (label → url). Labels are
-   * inserted in ascending version order, but JavaScript object semantics
-   * cap what insertion can promise: integer-like labels (bare majors such
-   * as `2`) always enumerate first, numerically, ahead of every dotted
-   * label — see {@link SchemaVersioning.catalogUrls} for the exact
-   * enumeration contract. Read version ordering from the labels, never
-   * from key position.
+   * 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,
- * a `versions` map, and `url` pointing at the latest version).
+ * `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 ordering follows SemVer precedence over labels padded to three
- * components, so `1.10` sorts above `1.9` and `2-beta` below `2`.
+ * 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
  */
@@ -240,9 +243,9 @@ declare class SchemaVersioning {
    */
   static readonly parse: (input: string) => Effect.Effect<string & import("effect/Brand").Brand<"SchemaVersion">, InvalidSchemaVersionError, never>;
   /**
-   * `Order` instance over version labels: SemVer precedence after padding
-   * missing components with zeros. `1.10` sorts above `1.9` (numeric, not
-   * lexical) and `2-beta` below `2` (prerelease precedence).
+   * `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>;
   /**
@@ -273,16 +276,13 @@ declare class SchemaVersioning {
    * a contradiction (versioned mode with no versions) and throws — pass
    * `undefined` for the unversioned mode.
    *
-   * Labels are inserted in ascending {@link SchemaVersioning.Order}, but
-   * the SchemaStore catalog format requires `versions` to be a JSON
-   * *object*, and JavaScript enumerates array-index-like keys first: a
-   * bare-major label (`"2"`) always enumerates — and therefore
-   * serializes — before every dotted label, regardless of insertion. The
-   * resulting enumeration order is: bare-major labels ascending
-   * numerically, then all other labels ascending. For label sets with no
-   * bare majors this is fully ascending; mixed sets interleave, so
-   * consumers must derive ordering from the labels themselves (as
-   * {@link SchemaVersioning.latest} does), never from key position.
+   * 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;
@@ -360,6 +360,84 @@ declare class CatalogEntry extends CatalogEntry_base {
   static lintFileMatch(patterns: ReadonlyArray<string>): ReadonlyArray<CatalogLintFinding>;
 }
 //#endregion
+//#region src/DocumentDiff.d.ts
+/**
+ * What differs between two schema documents:
+ *
+ * - `"none"` — the documents are equal in content (key ORDER is not a
+ *   difference; array order is).
+ * - `"annotations"` — only documentation keywords differ (see
+ *   {@link DocumentDiff.isAnnotationKeyword}). The validation contract is
+ *   identical, so the new document replaces the old transparently for
+ *   every consumer — republish without cutting a version.
+ * - `"contract"` — at least one assertion keyword differs, so a document
+ *   valid against one is not necessarily valid against the other. Under
+ *   {@link SchemaVersioning}, this is the change that warrants a new
+ *   version rather than an in-place replacement.
+ *
+ * @public
+ */
+type SchemaChange = "none" | "annotations" | "contract";
+/**
+ * Classifies the difference between two emitted schema documents by
+ * meaning: identical, documentation-only, or a change to the validation
+ * contract.
+ *
+ * The walk is keyword-position aware in exactly the way {@link DocumentLint}'s
+ * is — a property NAMED `description` inside `properties` is data, not an
+ * annotation — and object key order is never a difference, so a document
+ * reformatted (or key-sorted) by another tool still classifies as `"none"`.
+ *
+ * Total: hostile nesting past the package's depth cap stops the structural
+ * walk and degrades to a whole-subtree comparison reported as `"contract"`
+ * when unequal, never a throw.
+ *
+ * @example
+ * ```ts
+ * import { DocumentDiff } from "@effected/schemastore";
+ *
+ * const before = { type: "object", properties: { name: { type: "string", description: "A" } } };
+ * const after = { type: "object", properties: { name: { type: "string", description: "B" } } };
+ *
+ * console.log(DocumentDiff.classify(before, after));
+ * // => "annotations"  (republish transparently; no new version needed)
+ *
+ * console.log(DocumentDiff.classify(before, { ...before, required: ["name"] }));
+ * // => "contract"     (documents valid before may be invalid now)
+ * ```
+ *
+ * @public
+ */
+declare class DocumentDiff {
+  private constructor();
+  /**
+   * Classify the difference between two emitted document values (the
+   * `toJson()` publication shape, or anything parsed from a written
+   * schema file). Both sides are plain JSON values, so this compares an
+   * on-disk document against a freshly built one without either being a
+   * {@link StoreDocument}.
+   */
+  static classify(existing: unknown, next: unknown): SchemaChange;
+  /**
+   * Whether a classification means "nothing changed" — `true` only for
+   * `"none"`.
+   *
+   * Exists so the clean case is not a string literal every consumer
+   * spells for itself. `"created"` is deliberately NOT clean: a file that
+   * did not exist is a change.
+   */
+  static isClean(change: SchemaChange | "created"): boolean;
+  /**
+   * Whether `key`, standing at a schema position, is a documentation
+   * keyword: `title`, `description`, `$comment`, or any declared
+   * non-standard language-server family ({@link KeywordFamilies}).
+   *
+   * `default`, `examples`, `readOnly` and `writeOnly` are deliberately
+   * NOT documentation — consumers act on them.
+   */
+  static isAnnotationKeyword(key: string): boolean;
+}
+//#endregion
 //#region src/StoreDocument.d.ts
 /**
  * The Draft-07 meta-schema URL SchemaStore documents declare as `$schema`.
@@ -442,6 +520,33 @@ declare const StoreDocument_base: Schema.Class<StoreDocument, Schema.Struct<{
  * @public
  */
 declare class StoreDocument extends StoreDocument_base {
+  /**
+   * Builds a Draft-07 document from its parts, filling `$schema` with
+   * {@link DRAFT_07_META_SCHEMA}.
+   *
+   * `fromSchema` sets the meta-schema unconditionally; hand-building a
+   * value with `make` otherwise means importing the constant just to
+   * repeat what the package already knows. `$schema` stays a real field
+   * rather than a defaulted one — it declares the document's dialect, and
+   * a document that does not say which dialect it is written in is worse
+   * than one that repeats itself — so this is a constructor, not a
+   * default.
+   *
+   * @example
+   * ```ts
+   * import { StoreDocument } from "@effected/schemastore";
+   *
+   * const document = StoreDocument.draft07({
+   *   $id: "https://example.com/config.schema.json",
+   *   root: { type: "object" },
+   * });
+   * ```
+   */
+  static draft07(options: {
+    readonly $id: string;
+    readonly root: Record<string, unknown>;
+    readonly defs?: Record<string, unknown>;
+  }): StoreDocument;
   /**
    * Builds the document for an Effect Schema source. Pure and
    * synchronous — the primitive form; {@link StoreDocument.fromSchema} is
@@ -602,14 +707,89 @@ declare class SchemaFileWriteError extends SchemaFileWriteError_base {
   get message(): string;
 }
 /**
- * What {@link SchemaFileShape.write} did: `"written"` when the file's
- * content changed (or the file was created), `"unchanged"` when the
- * on-disk bytes already matched — reported as a value so the caller
- * decides what to surface, never a log.
+ * 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.
@@ -627,13 +807,26 @@ interface SchemaFileShape {
   /**
    * 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 the
-   * {@link WriteOutcome} as a value. 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).
+   * 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 write: (path: string, document: StoreDocument, options?: CanonicalJsonOptions) => Effect.Effect<WriteOutcome, CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError>;
+  readonly check: (path: string, document: StoreDocument, options?: SchemaWriteOptions) => Effect.Effect<CheckResult, CanonicalJsonError | SchemaFileReadError>;
 }
 declare const SchemaFile_base: Context.ServiceClass<SchemaFile, "@effected/schemastore/SchemaFile", SchemaFileShape>;
 /**
@@ -642,10 +835,14 @@ declare const SchemaFile_base: Context.ServiceClass<SchemaFile, "@effected/schem
  * services; provide `@effect/platform-node`'s `NodeFileSystem` / `NodePath`
  * (or a bun equivalent) at the application boundary.
  *
- * `write` is write-if-changed: serialization goes through the owned
- * `CanonicalJson` (equal documents serialize to equal bytes), so an
- * unchanged document never touches the file — a generator committed to a
- * repo does not churn mtimes, and its CI drift check is `read` + compare.
+ * `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
@@ -694,9 +891,17 @@ interface SchemaTarget {
   readonly schema: Schema.Constraint;
   /** The canonical `$id` URL the generated document declares. */
   readonly $id: string;
-  /** The catalog/file base name (`name.json` / `name-<version>.json`). */
-  readonly name: string;
-  /** The destination path the document is written to (phase-2 `SchemaFile`). */
+  /**
+   * The catalog/file base name (`name.json` / `name-<version>.json`).
+   *
+   * Only the catalog path consumes it — a target that merely emits a file
+   * to `path` needs no name, and inventing one to
+   * satisfy the constructor duplicates the basename with no invariant
+   * tying the two together. Required whenever `version` is present, since
+   * versioned catalog naming is defined in terms of it.
+   */
+  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. */
   readonly version?: SchemaVersion;
@@ -709,15 +914,27 @@ interface SchemaTarget {
 declare class SchemaTarget {
   private constructor();
   /**
-   * Builds a target. `$id`, `name` and `path` must be non-empty — an
-   * empty identity is a wiring mistake and throws.
+   * Builds an unversioned target. `name` is optional — only catalog
+   * naming reads it, so a target that merely emits a file needs none.
+   */
+  static make(options: {
+    readonly schema: Schema.Constraint;
+    readonly $id: string;
+    readonly name?: string;
+    readonly path: string;
+  }): SchemaTarget;
+  /**
+   * Builds a versioned target. `name` is **required** here: versioned
+   * catalog naming is `name-<version>.json`, so a version without a name
+   * cannot be resolved — the overload pair makes that unrepresentable
+   * rather than a runtime throw.
    */
   static make(options: {
     readonly schema: Schema.Constraint;
     readonly $id: string;
     readonly name: string;
     readonly path: string;
-    readonly version?: SchemaVersion;
+    readonly version: SchemaVersion;
   }): SchemaTarget;
 }
 //#endregion
@@ -788,17 +1005,22 @@ interface SchemaValidatorShape {
 }
 declare const SchemaValidator_base: Context.ServiceClass<SchemaValidator, "@effected/schemastore/SchemaValidator", SchemaValidatorShape>;
 /**
- * Contract for real-engine JSON Schema document validation — the seam
- * through which SchemaStore's own gate (ajv strict mode) reaches this
- * package without ajv ever entering its dependency graph.
+ * Real-engine JSON Schema document validation, closed by default over ajv —
+ * the engine SchemaStore's own gate is defined in terms of.
+ *
+ * {@link SchemaValidator.layer} is the shipped implementation: provide it and
+ * validation works, with no adapter to write. The service stays an interface
+ * so a test can swap it ({@link SchemaValidator.layerTest}) or skip it
+ * ({@link SchemaValidator.noop}), and so a consumer standardized on a
+ * different engine can substitute one — but writing an adapter is no longer
+ * the price of admission. `DocumentLint` remains the owned, engine-free
+ * structural half of the validation story, and answers questions ajv does
+ * not (SchemaStore's own hygiene conventions).
  *
- * This is a contract-only service: {@link SchemaValidator.noop} is the sole
- * implementation this package ships, and it validates nothing. The consumer
- * closes the seam with a real engine at the application edge — e.g. an ajv
- * adapter whose `validate` compiles the document with
- * `new Ajv({ strict: true, allErrors: true })` and answers compile failures
- * as findings. `DocumentLint` remains the owned, always-available
- * structural half of the validation story.
+ * The shipped layer registers every declared {@link KeywordFamilies} keyword
+ * present in the document before compiling, so ajv strict mode does not
+ * reject the language-server families `DocumentLint` deliberately allows —
+ * one predicate governs both verdicts.
  *
  * @example
  * ```ts
@@ -810,7 +1032,7 @@ declare const SchemaValidator_base: Context.ServiceClass<SchemaValidator, "@effe
  *   return yield* validator.validate({ type: "object" });
  * });
  *
- * Effect.runPromise(Effect.provide(program, SchemaValidator.noop));
+ * Effect.runPromise(Effect.provide(program, SchemaValidator.layer));
  * // => []
  * ```
  *
@@ -818,9 +1040,24 @@ declare const SchemaValidator_base: Context.ServiceClass<SchemaValidator, "@effe
  */
 declare class SchemaValidator extends SchemaValidator_base {
   /**
-   * No-op default: `validate` always succeeds with no findings, never
-   * consulting an engine. A pure `Layer.succeed`, bound to a const so the
-   * layer memoizes by reference.
+   * 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.
+   *
+   * `strict` defaults to `true` — SchemaStore's gate. Each call builds its
+   * own ajv instance, so documents sharing an `$id` never collide.
+   */
+  static readonly layer: Layer.Layer<SchemaValidator>;
+  /**
+   * No-op: `validate` always succeeds with no findings, never consulting an
+   * engine. A pure `Layer.succeed`, bound to a const so the layer memoizes
+   * by reference. Use it to switch validation off deliberately — for the
+   * real engine, provide {@link SchemaValidator.layer}.
    */
   static readonly noop: Layer.Layer<SchemaValidator>;
   /**
@@ -835,5 +1072,205 @@ declare class SchemaValidator extends SchemaValidator_base {
   static readonly layerTest: (overrides?: Partial<SchemaValidatorShape>) => Layer.Layer<SchemaValidator>;
 }
 //#endregion
-export { AnnotationCarriers, CanonicalJson, type CanonicalJsonError, type CanonicalJsonOptions, CarrierDepthExceededError, CatalogEntry, CatalogLintFinding, type CatalogUrls, DRAFT_07_META_SCHEMA, DocumentLint, DocumentLintFinding, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, type SchemaFileShape, SchemaFileWriteError, SchemaTarget, SchemaValidator, SchemaValidatorError, type SchemaValidatorOptions, type SchemaValidatorShape, SchemaVersion, SchemaVersioning, StoreDocument, type StoreDocumentOptions, ValidationFinding, type WriteOutcome };
+//#region src/SchemaPipeline.d.ts
+declare const PipelineFinding_base: Schema.Class<PipelineFinding, Schema.Struct<{
+  /** Which gate produced it. */
+  readonly source: Schema.Literals<readonly ["lint", "validator"]>;
+  /** `"warning"` blocks under the default policy; `"advisory"` does not. */
+  readonly severity: Schema.Literals<readonly ["warning", "advisory"]>;
+  /** The lint check's name, or the engine keyword, when one is named. */
+  readonly check: Schema.optionalKey<Schema.String>;
+  /** JSON pointer into the flat document (`""` is the root). */
+  readonly path: Schema.String;
+  /** Human-readable explanation. */
+  readonly message: Schema.String;
+}>, {}>;
+/**
+ * One problem found while emitting a target, from either gate, normalized
+ * so a single policy predicate can judge both.
+ *
+ * `DocumentLint` findings keep their own severity; engine findings are
+ * `"warning"` — a document the engine rejects is not advisory.
+ *
+ * @public
+ */
+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.
+   *
+   * Engine findings do not always carry a keyword, so without this every
+   * consumer that logs findings writes the same `finding.check ?? …`
+   * fallback.
+   */
+  get label(): string;
+}
+declare const SchemaGateError_base: Schema.Class<SchemaGateError, Schema.TaggedStruct<"SchemaGateError", {
+  /** The `$id` of the target that failed the gate. */
+  readonly $id: Schema.String;
+  /** Every finding that blocked, in discovery order. */
+  readonly findings: Schema.$Array<typeof PipelineFinding>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that at least one target's findings blocked under the active
+ * gating policy. Carries every blocking finding, so a caller renders one
+ * report instead of discovering problems one run at a time.
+ *
+ * @public
+ */
+declare class SchemaGateError extends SchemaGateError_base {
+  get message(): string;
+}
+/**
+ * What the pipeline did with one target.
+ *
+ * @public
+ */
+interface PipelineResult {
+  /** The target's `$id`. */
+  readonly $id: string;
+  /** The path the document was written to (or compared against). */
+  readonly path: string;
+  /** Whether the file was written. Absent from {@link SchemaPipeline.check}'s results. */
+  readonly outcome: WriteOutcome;
+  /** What differs between the previous content and the new document. */
+  readonly change: WriteChange;
+  /**
+   * Every finding, blocking or not — returned as a value, never logged.
+   * The package does not choose your log wording; a run that reached a
+   * result had no blocking findings under the active policy.
+   */
+  readonly findings: ReadonlyArray<PipelineFinding>;
+}
+/**
+ * What {@link SchemaPipeline.check} found for one target — the same report
+ * without the write.
+ *
+ * @public
+ */
+interface PipelineCheckResult {
+  /** The target's `$id`. */
+  readonly $id: string;
+  /** The path compared against. */
+  readonly path: string;
+  /** Whether a run would touch this file. */
+  readonly wouldWrite: boolean;
+  /**
+   * Whether this target's findings would block a {@link SchemaPipeline.run}
+   * under the active policy — so a document that could never be written is
+   * never mistaken for clean drift.
+   */
+  readonly blocked: boolean;
+  /** What differs between the on-disk content and the new document. */
+  readonly change: WriteChange;
+  /** Every finding, blocking or not. */
+  readonly findings: ReadonlyArray<PipelineFinding>;
+}
+/**
+ * Options for {@link SchemaPipeline.run} and {@link SchemaPipeline.check}.
+ *
+ * @public
+ */
+interface SchemaPipelineOptions {
+  /**
+   * Which findings block. Defaults to
+   * `(finding) => finding.severity === "warning"`.
+   *
+   * The default is a policy call, not a mechanism: `UnresolvedRef`,
+   * `UnknownKeyword` and `DepthExceeded` each describe a document that is
+   * broken for the editors it exists to serve, and `UnknownKeyword` is by
+   * construction the ajv-strict rejection set — tolerating it means
+   * shipping something the engine gate rejects. A consumer who disagrees
+   * replaces this predicate rather than re-implementing the loop.
+   *
+   * **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
+   * 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;
+  /** Passed through to `SchemaValidator.validate`. */
+  readonly validator?: SchemaValidatorOptions;
+  /** Passed through to `SchemaFile.write` / `SchemaFile.check`. */
+  readonly write?: SchemaWriteOptions;
+}
+/**
+ * The emit pipeline over a target manifest: generate, lint, validate, gate,
+ * write — the loop every consumer of this package was writing by hand.
+ *
+ * Requires `SchemaFile` and `SchemaValidator` in `R`; provide
+ * `SchemaFile.layer` and `SchemaValidator.layer` (plus a platform
+ * `FileSystem` / `Path`) at the edge. Findings come back as **values**, so
+ * the package never chooses your log wording — but the gating decision,
+ * which is the part that must not silently differ between consumers, has
+ * one default and one override point.
+ *
+ * @example
+ * ```ts
+ * import { SchemaFile, SchemaPipeline, SchemaTarget, SchemaValidator } from "@effected/schemastore";
+ * import { NodeServices } from "@effect/platform-node";
+ * import { Effect, Layer, Schema } from "effect";
+ *
+ * const targets = [
+ *   SchemaTarget.make({
+ *     schema: Schema.Struct({ name: Schema.String }),
+ *     $id: "https://example.com/config.schema.json",
+ *     path: "schemas/config.schema.json",
+ *   }),
+ * ];
+ *
+ * const program = SchemaPipeline.run(targets).pipe(
+ *   Effect.provide(Layer.mergeAll(SchemaFile.layer, SchemaValidator.layer)),
+ *   Effect.provide(NodeServices.layer),
+ * );
+ * ```
+ *
+ * @public
+ */
+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.
+   *
+   * 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.
+   */
+  static run(targets: ReadonlyArray<SchemaTarget>, options?: SchemaPipelineOptions): Effect.Effect<ReadonlyArray<PipelineResult>, SchemaGateError | 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.
+   *
+   * Unlike {@link SchemaPipeline.run} this is **total over the targets**:
+   * it never stops at a failing gate, and reports `blocked` per target
+   * instead of failing. Reporting is the job here, and a repo with three
+   * broken documents should learn that in one run rather than fixing them
+   * one run at a time. A blocked target is still never mistaken for clean
+   * drift — `blocked` says so explicitly.
+   *
+   * 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>;
+  /**
+   * {@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>;
+  /**
+   * {@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>;
+}
+//#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 };
 //# sourceMappingURL=index.d.ts.map