@effected/schemastore 0.1.0

package/index.d.ts

@@ -0,0 +1,839 @@
+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). */
+  readonly path: Schema.String;
+  /** The `typeof`/structural description of the rejected value. */
+  readonly found: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a value reachable from the serialization input is not a
+ * JSON value: `undefined`, a function, a symbol, a `bigint`, a non-finite
+ * number, or an object that is neither an array nor a plain object.
+ *
+ * Raised by {@link CanonicalJson.serialize}. Unlike `JSON.stringify` — which
+ * silently drops `undefined` members and rewrites `NaN`/`Infinity` to
+ * `null` — canonical serialization refuses to alter the document, so every
+ * non-JSON value is a typed failure carrying the path to fix.
+ *
+ * @public
+ */
+declare class NonJsonValueError extends NonJsonValueError_base {
+  get message(): string;
+}
+declare const JsonDepthExceededError_base: Schema.Class<JsonDepthExceededError, Schema.TaggedStruct<"JsonDepthExceededError", {
+  /** JSON pointer to the node 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 serialization input nests deeper than the package's
+ * hardening cap (256 levels), which also intercepts cyclic values before
+ * they can recurse forever.
+ *
+ * Raised by {@link CanonicalJson.serialize}.
+ *
+ * @public
+ */
+declare class JsonDepthExceededError extends JsonDepthExceededError_base {
+  get message(): string;
+}
+/**
+ * Union of the failures {@link CanonicalJson.serialize} can raise.
+ *
+ * @public
+ */
+type CanonicalJsonError = NonJsonValueError | JsonDepthExceededError;
+/**
+ * Options for {@link CanonicalJson.serialize}.
+ *
+ * @public
+ */
+interface CanonicalJsonOptions {
+  /**
+   * Indentation unit: `"tab"` (the default, matching the repo formatter
+   * convention the extraction source committed its files under) or a
+   * space count — a non-negative integer (`0` emits multi-line output
+   * with no leading indentation). Counts above 10 are honored as given,
+   * deliberately diverging from `JSON.stringify`'s silent clamp to 10.
+   * A negative or fractional count is a wiring mistake and throws (the
+   * serializer alters nothing silently — not even its own options).
+   */
+  readonly indent?: "tab" | number;
+}
+/**
+ * Deterministic, canonical JSON text: the package's owned serializer, so a
+ * consumer never shells out to an external formatter to produce a stable
+ * committed schema file.
+ *
+ * The canonical form is fully specified: object keys in insertion order
+ * (document assembly owns meaningful ordering — keys are never sorted),
+ * every array element and object member on its own line, the configured
+ * indent (tab by default), `"` string escaping exactly as `JSON.stringify`
+ * produces it, LF line endings and a single trailing newline. Equal inputs
+ * serialize to equal bytes.
+ *
+ * Values that are not JSON fail typed rather than being silently rewritten
+ * (see {@link NonJsonValueError}); nesting past the hardening cap — which
+ * includes cyclic values — fails with {@link JsonDepthExceededError}.
+ *
+ * @public
+ */
+declare class CanonicalJson {
+  private constructor();
+  /**
+   * Serializes `value` to canonical JSON text. Pure and synchronous — the
+   * primitive form; {@link CanonicalJson.serialize} is the same engine
+   * behind a span.
+   */
+  static serializeResult(value: unknown, options?: CanonicalJsonOptions): Result.Result<string, CanonicalJsonError>;
+  /**
+   * Effect form of {@link CanonicalJson.serializeResult}, adding only the
+   * `CanonicalJson.serialize` span. Defined in terms of the `Result`
+   * primitive — synchronous callers can use that variant directly.
+   */
+  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 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}).
+ *
+ * @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). 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.
+   */
+  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).
+ *
+ * Version ordering follows SemVer precedence over labels padded to three
+ * components, so `1.10` sorts above `1.9` and `2-beta` below `2`.
+ *
+ * @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: SemVer precedence after padding
+   * missing components with zeros. `1.10` sorts above `1.9` (numeric, not
+   * lexical) and `2-beta` below `2` (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}, 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.
+   */
+  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/StoreDocument.d.ts
+/**
+ * The Draft-07 meta-schema URL SchemaStore documents declare as `$schema`.
+ *
+ * Deliberately carries the trailing `#` fragment: the SchemaStore corpus
+ * (and the extraction source's committed files) use the fragment form,
+ * where core's `JsonSchema.META_SCHEMA_URI_DRAFT_07` omits it.
+ *
+ * @public
+ */
+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;
+  /** The underlying conversion failure. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that an Effect Schema could not be converted into a SchemaStore
+ * document — core's JSON Schema generation rejected the schema, or the
+ * generated document nested past the hardening cap.
+ *
+ * Raised by {@link StoreDocument.fromSchema}. The `cause` carries the
+ * underlying failure for the operator; calling code branches on the tag.
+ *
+ * @public
+ */
+declare class SchemaConversionError extends SchemaConversionError_base {
+  get message(): string;
+}
+/**
+ * Options for {@link StoreDocument.fromSchema}.
+ *
+ * @public
+ */
+interface StoreDocumentOptions {
+  /** The canonical `$id` URL the document declares. */
+  readonly $id: string;
+  /**
+   * Passed through to core's `Schema.toJsonSchemaDocument`
+   * (`additionalProperties`, `generateDescriptions`,
+   * `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.
+   */
+  readonly jsonSchema?: Schema.ToJsonSchemaOptions;
+}
+declare const StoreDocument_base: Schema.Class<StoreDocument, Schema.Struct<{
+  /** The meta-schema URL ({@link DRAFT_07_META_SCHEMA}). */
+  readonly $schema: Schema.String;
+  /** The canonical `$id` URL. */
+  readonly $id: Schema.String;
+  /** The root schema's keywords, without the definitions pool. */
+  readonly root: Schema.$Record<Schema.String, Schema.Unknown>;
+  /** The definitions pool, emitted under `$defs`. */
+  readonly defs: Schema.$Record<Schema.String, Schema.Unknown>;
+}>, {}>;
+/**
+ * A SchemaStore-shaped Draft-07 JSON Schema document assembled from an
+ * Effect Schema source: `$schema` (the Draft-07 meta-schema) + `$id` + the
+ * root schema + the `$defs` pool.
+ *
+ * {@link StoreDocument.fromSchema} owns the whole pipeline: core's
+ * `Schema.toJsonSchemaDocument` (Draft 2020-12), core's
+ * `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.
+ *
+ * @public
+ */
+declare class StoreDocument extends StoreDocument_base {
+  /**
+   * Builds the document for an Effect Schema source. Pure and
+   * 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>;
+  /**
+   * 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>;
+  /**
+   * 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>;
+  /**
+   * 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/DocumentLint.d.ts
+declare const DocumentLintFinding_base: Schema.Class<DocumentLintFinding, Schema.Struct<{
+  /** Which check fired. */
+  readonly check: Schema.Literals<readonly ["UnresolvedRef", "UnknownKeyword", "DescriptionWithoutUrl", "DepthExceeded"]>;
+  /** `"warning"` for structural defects, `"advisory"` for best practices. */
+  readonly severity: Schema.Literals<readonly ["warning", "advisory"]>;
+  /** JSON pointer into the flat document (`""` is the root schema). */
+  readonly path: Schema.String;
+  /** Human-readable explanation. */
+  readonly message: Schema.String;
+}>, {}>;
+/**
+ * A structural lint finding over an assembled document: a value in a
+ * report, never an error channel — a document with findings is still a
+ * document, and the consumer decides what a finding gates.
+ *
+ * @public
+ */
+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
+ * ajv strict mode stays at the consumer's edge):
+ *
+ * - `UnresolvedRef` — every `$ref` resolves against the `$defs` pool
+ *   (`#` self-refs allowed; anything else, including a surviving
+ *   `#/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.
+ * - `DescriptionWithoutUrl` — advisory: SchemaStore's description
+ *   convention ends the root description with a docs URL line.
+ *
+ * Tractable because the input is bounded `toJsonSchemaDocument` output;
+ * this is not a general JSON Schema validator.
+ *
+ * @public
+ */
+declare class DocumentLint {
+  private constructor();
+  /**
+   * Runs every check; total — hostile nesting degrades to a
+   * `DepthExceeded` finding rather than an error.
+   */
+  static lint(document: StoreDocument): ReadonlyArray<DocumentLintFinding>;
+}
+//#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:
+ *
+ * - **vscode-json-languageservice** (exact names): `allowTrailingCommas`,
+ *   `defaultSnippets`, `enumDescriptions`, `markdownDescription`,
+ *   `markdownEnumDescriptions`.
+ * - **taplo**: the `x-taplo` prefix (`x-taplo`, `x-taplo-info`, ...).
+ * - **tombi**: the `x-tombi-` prefix (`x-tombi-toml-version`,
+ *   `x-tombi-array-values-order`, `x-tombi-array-values-order-by`,
+ *   `x-tombi-table-keys-order`, `x-tombi-string-formats`,
+ *   `x-tombi-additional-key-label`).
+ * - **IntelliJ**: the `x-intellij-` prefix (`x-intellij-language-injection`,
+ *   `x-intellij-html-description`, `x-intellij-enum-metadata`).
+ *
+ * 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.
+ */
+/**
+ * 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.
+ *
+ * @public
+ */
+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.
+   */
+  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: `"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.
+ *
+ * @public
+ */
+type WriteOutcome = "written" | "unchanged";
+/**
+ * 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 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).
+   */
+  readonly write: (path: string, document: StoreDocument, options?: CanonicalJsonOptions) => Effect.Effect<WriteOutcome, CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError>;
+}
+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: 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.
+ *
+ * @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
+ * the identity and destination it is serialized under. A repo generating
+ * SchemaStore artifacts declares one target per emitted document (the
+ * extraction source's `{schema, $id, path}` triples, generalized).
+ *
+ * Not a `Schema.Class`: a target carries a live Effect Schema value, which
+ * is program wiring rather than serializable data.
+ *
+ * @public
+ */
+interface SchemaTarget {
+  /** The Effect Schema source the document is generated from. */
+  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`). */
+  readonly path: string;
+  /** The version label, for versioned catalog mode. Omit for unversioned. */
+  readonly version?: SchemaVersion;
+}
+/**
+ * Constructors for `SchemaTarget` values.
+ *
+ * @public
+ */
+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.
+   */
+  static make(options: {
+    readonly schema: Schema.Constraint;
+    readonly $id: string;
+    readonly name: string;
+    readonly path: string;
+    readonly version?: SchemaVersion;
+  }): SchemaTarget;
+}
+//#endregion
+//#region src/SchemaValidator.d.ts
+declare const SchemaValidatorError_base: Schema.Class<SchemaValidatorError, Schema.TaggedStruct<"SchemaValidatorError", {
+  /** The underlying engine failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that the validation engine behind the {@link SchemaValidator}
+ * contract failed as a *mechanism* — it could not run at all.
+ *
+ * By convention the error channel is reserved for exactly that: a document
+ * that fails the engine's gate is a {@link ValidationFinding} list (a
+ * value), never an error. Raised by implementations of
+ * {@link SchemaValidatorShape.validate}.
+ *
+ * @public
+ */
+declare class SchemaValidatorError extends SchemaValidatorError_base {
+  get message(): string;
+}
+declare const ValidationFinding_base: Schema.Class<ValidationFinding, Schema.Struct<{
+  /** JSON pointer into the flat document (`""` is the root schema). */
+  readonly path: Schema.String;
+  /** Human-readable explanation from the engine. */
+  readonly message: Schema.String;
+  /** The JSON Schema keyword the finding is about, when the engine names one. */
+  readonly keyword: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One problem a validation engine found with a document: a value in a
+ * report, never an error channel — the consumer decides what a finding
+ * gates.
+ *
+ * @public
+ */
+declare class ValidationFinding extends ValidationFinding_base {}
+/**
+ * Options for {@link SchemaValidatorShape.validate}.
+ *
+ * @public
+ */
+interface SchemaValidatorOptions {
+  /**
+   * Whether the engine runs its strictest mode (ajv `strict: true` — the
+   * SchemaStore default gate). Defaults to `true`; implementations treat
+   * an omitted value as strict.
+   */
+  readonly strict?: boolean;
+}
+/**
+ * The shape of the {@link SchemaValidator} service — what an implementation
+ * provides.
+ *
+ * @public
+ */
+interface SchemaValidatorShape {
+  /**
+   * Validates a flat schema document (each `ValidationFinding.path`
+   * pointer addresses `StoreDocument.toJson()`'s shape) with a real JSON
+   * Schema engine. An empty array is a clean pass; a document the engine
+   * rejects — including an ajv strict-mode compile failure — answers
+   * findings as values. The error channel is reserved for the engine
+   * failing as a mechanism ({@link SchemaValidatorError}).
+   */
+  readonly validate: (document: Record<string, unknown>, options?: SchemaValidatorOptions) => Effect.Effect<ReadonlyArray<ValidationFinding>, SchemaValidatorError>;
+}
+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.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { SchemaValidator } from "@effected/schemastore";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const validator = yield* SchemaValidator;
+ *   return yield* validator.validate({ type: "object" });
+ * });
+ *
+ * Effect.runPromise(Effect.provide(program, SchemaValidator.noop));
+ * // => []
+ * ```
+ *
+ * @public
+ */
+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.
+   */
+  static readonly noop: Layer.Layer<SchemaValidator>;
+  /**
+   * An in-memory double: stub only the members the test exercises; every
+   * other member **dies** with a defect naming itself. No member has an
+   * honest default — a fabricated clean pass would leak into consumer
+   * logic as fact (use {@link SchemaValidator.noop} when a test genuinely
+   * wants an always-clean validator).
+   */
+  static readonly makeTest: (overrides?: Partial<SchemaValidatorShape>) => SchemaValidatorShape;
+  /** {@link SchemaValidator.makeTest} behind `Layer.succeed`. */
+  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 };
+//# sourceMappingURL=index.d.ts.map