@effected/schemastore 0.10.0 → 0.12.0

package/index.d.ts

@@ -264,6 +264,14 @@ interface StoreDocumentOptions {
    * (`onExcessProperty`, `generateDescriptions`,
    * `includeAnnotationKey`).
    *
+   * `onExcessProperty` defaults to `"error"` here — every object is
+   * emitted closed (`additionalProperties: false`) because a published
+   * document is a contract — where core's own default has been `"ignore"`
+   * (open) since rc.113. Pass `{ onExcessProperty: "ignore" }` to reopen
+   * one document's objects. Omitting `jsonSchema` altogether reproduces
+   * byte-for-byte what the CLI writes for a target that declares none — a
+   * consumer test may call `fromSchemaResult(schema, { $id })` and compare.
+   *
    * The declared non-standard keyword families ({@link KeywordFamilies})
    * are **always admitted**, regardless of what a supplied
    * `includeAnnotationKey` answers — annotate a schema node
@@ -650,6 +658,16 @@ export declare const SchemaVersion: Schema.brand<Schema.String, "SchemaVersion">
  * @public
  */
 export type SchemaVersion = typeof SchemaVersion.Type;
+/**
+ * Where a versioned document sits relative to its base: `flat` is
+ * `<name>-<version>.json` (the only shape SchemaStore serves), `versioned`
+ * nests it as `<version>/<name>-<version>.json` — or, with `appendVersion`
+ * off, `<version>/<name>.json`, the directory alone carrying the label. An
+ * unversioned document is `<name>.json` under either.
+ *
+ * @public
+ */
+type SchemaLayout = "flat" | "versioned";
 /**
  * The `url`/`versions` half of a catalog entry, as assembled by
  * {@link SchemaVersioning.catalogUrls}.
@@ -756,28 +774,51 @@ export declare class SchemaVersioning {
    * the label and the ceiling rather than `SemVer.make`'s bare schema failure.
    */
   static next(current: SchemaVersion, change: WriteChange): SchemaVersion;
+  /**
+   * Whether a name is a simple file base name — non-empty, no path
+   * separators, no whitespace — the rule every schema name is held to
+   * ({@link SchemaVersioning.fileName} throws on anything else; `defineConfig`
+   * rejects a schema key the same way). One predicate so the two cannot drift.
+   */
+  static isSimpleName(name: string): boolean;
   /**
    * Derives the schema file name for a catalog name: `name.json`
-   * unversioned, `name-<version>.json` versioned.
+   * unversioned, `name-<version>.json` versioned under the `"flat"`
+   * layout (the default and the only shape SchemaStore serves), or
+   * `<version>/name-<version>.json` under `"versioned"` — `<version>/name.json`
+   * when `appendVersion` is `false`, which only the versioned layout can
+   * carry (under `"flat"` two versions would share one file name, so that
+   * combination throws).
    *
    * 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;
+  static fileName(name: string, version?: SchemaVersion, layout?: SchemaLayout, appendVersion?: boolean): 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;
+  static schemaUrl(baseUrl: string, name: string, version?: SchemaVersion, layout?: SchemaLayout, appendVersion?: boolean): 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
+   * points at `current` (default: the newest label under
+   * {@link SchemaVersioning.Order}). An **empty** `versions` array is
    * a contradiction (versioned mode with no versions) and throws — pass
-   * `undefined` for the unversioned mode.
+   * `undefined` for the unversioned mode. `current`, when given, must
+   * compare equal under {@link SchemaVersioning.Order} to a member of
+   * `versions` or this throws; `url` is built from that member's own
+   * spelling (the `versions` map's key), not from the `current` argument
+   * verbatim — so a differently-spelled equivalent (`"1.2"` matching a
+   * `"1.2.0"` member) still points `url` at the same file the map does.
+   *
+   * `layout` (default `"flat"`) and `appendVersion` (default `true`) are
+   * forwarded to every URL derivation, so `"versioned"` nests every map
+   * value and `url` under its own version directory, with or without the
+   * `-<version>` file suffix.
    *
    * Labels are inserted in ascending {@link SchemaVersioning.Order}; see
    * {@link CatalogUrls.versions} for why a bare-major key's serialized
@@ -787,6 +828,9 @@ export declare class SchemaVersioning {
     readonly baseUrl: string;
     readonly name: string;
     readonly versions?: ReadonlyArray<SchemaVersion>;
+    readonly layout?: SchemaLayout;
+    readonly appendVersion?: boolean;
+    readonly current?: SchemaVersion;
   }): CatalogUrls;
 }
 //#endregion
@@ -836,7 +880,10 @@ export declare class CatalogEntry extends CatalogEntry_base {
    * Assembles an entry from a catalog identity plus
    * {@link SchemaVersioning.catalogUrls}' inputs: pass `versions` for the
    * versioned mode (the `versions` map and latest-pointing `url` are
-   * derived), omit it for the unversioned mode. Throws an `Error` naming
+   * derived), omit it for the unversioned mode. `layout` (default
+   * `"flat"`), `appendVersion` (default `true`) and `current` (default: the
+   * newest label) are forwarded to {@link SchemaVersioning.catalogUrls}
+   * verbatim. Throws an `Error` naming
    * both spellings when two labels compare equal under
    * {@link SchemaVersioning.Order} (`1.2` and `1.2.0`): each would be its
    * own key and URL for one document.
@@ -848,6 +895,9 @@ export declare class CatalogEntry extends CatalogEntry_base {
     readonly baseUrl: string;
     readonly fileBaseName?: string;
     readonly versions?: ReadonlyArray<SchemaVersion>;
+    readonly layout?: SchemaLayout;
+    readonly appendVersion?: boolean;
+    readonly current?: SchemaVersion;
   }): CatalogEntry;
   /**
    * The fileMatch hygiene lint over this entry's patterns — pure shape
@@ -975,6 +1025,135 @@ export declare class DriftPolicy {
   }, policy: DriftTolerance): DriftVerdict;
 }
 //#endregion
+//#region src/HostedSchema.d.ts
+/** The host SchemaStore-hosted documents declare in `$id`. @public */
+export declare const SCHEMASTORE_ID_BASE = "https://json.schemastore.org";
+/** The host SchemaStore's `catalog.json` points `url` at. @public */
+export declare const SCHEMASTORE_CATALOG_BASE = "https://www.schemastore.org";
+/**
+ * The identity every hosted document derives from: `versions` and `current`
+ * as `defineConfig` accepts them, minus the host, which each constructor
+ * supplies.
+ *
+ * @public
+ */
+interface HostedSchemaVersionsInput {
+  /** The schema's file base name — the key it takes in `defineConfig`'s `schemas`. */
+  readonly name: string;
+  /** Every version label the schema advertises; omit for an unversioned schema. */
+  readonly versions?: ReadonlyArray<string>;
+  /** Which of `versions` is current. Defaults to the newest under {@link SchemaVersioning.Order}. */
+  readonly current?: string;
+  /**
+   * Whether a versioned file name carries the `-<version>` suffix
+   * (`<version>/<name>-<version>.json`, SchemaStore's own convention, the
+   * default) or the version directory alone names it
+   * (`<version>/<name>.json`). `false` requires the `"versioned"` layout
+   * and is rejected under `"flat"`, including SchemaStore hosting.
+   */
+  readonly appendVersion?: boolean;
+}
+/** Input to {@link HostedSchema.github}. @public */
+interface GitHubHostedSchemaInput extends HostedSchemaVersionsInput {
+  /** The repository, as `owner/repo`. */
+  readonly repo: string;
+  /** The branch (or tag) the files are served from. Defaults to `"main"`. */
+  readonly branch?: string;
+  /** The directory under the repository root the files live in, e.g. `"schemas"`. Defaults to the root. */
+  readonly path?: string;
+  /** How a versioned file nests under `path`. Defaults to `"versioned"`. */
+  readonly layout?: SchemaLayout;
+}
+/** Input to {@link HostedSchema.custom}. @public */
+interface CustomHostedSchemaInput extends HostedSchemaVersionsInput {
+  /** The `https://` directory URL the files are served under; a trailing slash is trimmed. */
+  readonly baseUrl: string | URL;
+  /** How a versioned file nests under `baseUrl`. Defaults to `"versioned"`. */
+  readonly layout?: SchemaLayout;
+}
+declare const HostedSchema_base: Schema.Class<HostedSchema, Schema.Struct<{
+  readonly name: Schema.String;
+  readonly baseUrl: Schema.String;
+  readonly versions: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly current: Schema.optionalKey<Schema.String>;
+  readonly layout: Schema.optionalKey<Schema.Literals<readonly ["flat", "versioned"]>>;
+  readonly appendVersion: Schema.optionalKey<Schema.Boolean>;
+}>, {}>;
+/**
+ * Where a JSON Schema document is hosted and which version of it is current
+ * — the one value an application derives its `$schema` URL from and hands
+ * to `defineConfig`, so the URL the code emits and the `$id` the CLI writes
+ * cannot disagree.
+ *
+ * @remarks
+ * Build one with {@link HostedSchema.github},
+ * {@link HostedSchema.schemastore} or
+ * {@link HostedSchema.custom}; each validates the identity and
+ * throws a plain `Error` naming the reason. The derivation is
+ * {@link SchemaVersioning.schemaUrl}'s: `<base>/<name>.json` unversioned,
+ * `<base>/<name>-<version>.json` under the `"flat"` layout and
+ * `<base>/<version>/<name>-<version>.json` under `"versioned"` (or
+ * `<base>/<version>/<name>.json` with `appendVersion: false`, when the
+ * version directory alone should name the file). The raw fields are what
+ * `defineConfig` accepts by hand (`baseUrl`, `versions`, `current`,
+ * `layout`, `appendVersion`); the getters are the resolved identity.
+ *
+ * @example
+ * ```ts
+ * import { HostedSchema } from "@effected/schemastore";
+ * import { Schema } from "effect";
+ *
+ * export const OutputSchema = HostedSchema.github({
+ *   repo: "savvy-web/silk-release-action",
+ *   path: "schemas",
+ *   name: "silk-release-action.output",
+ *   versions: ["5.2"],
+ * });
+ *
+ * // In the application: every payload names the schema it was written against.
+ * const Output = Schema.Struct({ $schema: Schema.Literal(OutputSchema.$id) });
+ *
+ * // In schemastore.config.ts: the same value, so nothing is re-derived.
+ * // schemas: { [OutputSchema.name]: { schema: Output, hosted: OutputSchema } }
+ * ```
+ *
+ * @public
+ */
+export declare class HostedSchema extends HostedSchema_base {
+  /** A schema served raw from a GitHub repository. */
+  static github(input: GitHubHostedSchemaInput): HostedSchema;
+  /** A schema published to SchemaStore: `$id` on {@link SCHEMASTORE_ID_BASE}, catalog URL on {@link SCHEMASTORE_CATALOG_BASE}, flat layout. */
+  static schemastore(input: HostedSchemaVersionsInput): HostedSchema;
+  /** A schema served from any `https://` directory. */
+  static custom(input: CustomHostedSchemaInput): HostedSchema;
+  private get resolved();
+  /** The base `$id` is derived from: {@link SCHEMASTORE_ID_BASE} under SchemaStore, else `baseUrl`. */
+  get idBase(): string;
+  /** The base the catalog URL is derived from: {@link SCHEMASTORE_CATALOG_BASE} under SchemaStore, else `baseUrl`. */
+  get catalogBase(): string;
+  /** The effective layout: `"flat"` under SchemaStore, else `layout` defaulting to `"versioned"`. */
+  get resolvedLayout(): SchemaLayout;
+  /** Whether versioned file names carry the `-<version>` suffix: `appendVersion` defaulting to `true`. */
+  get resolvedAppendVersion(): boolean;
+  /** Every advertised version, parsed; empty for an unversioned schema. */
+  get resolvedVersions(): ReadonlyArray<SchemaVersion>;
+  /** The current version — `current`, else the newest of `versions`; `undefined` for an unversioned schema. */
+  get resolvedCurrent(): SchemaVersion | undefined;
+  /** The `$id` of the current document — what an application writes as `$schema`. */
+  get $id(): string;
+  /** The catalog URL of the current document; equals {@link HostedSchema.$id} except under SchemaStore. */
+  get url(): string;
+  /** The current document's file name relative to the output directory. */
+  get fileName(): string;
+  /** The `$id` of the document at `version` (or the unversioned document). */
+  idFor(version?: string): string;
+  /** The catalog URL of the document at `version` (or the unversioned document). */
+  urlFor(version?: string): string;
+  /** The file name of the document at `version` (or the unversioned document), relative to the output directory. */
+  fileNameFor(version?: string): string;
+  private parseLabel;
+}
+//#endregion
 //#region src/KeywordFamilies.d.ts
 /**
  * The one owner of the declared non-standard keyword families, in two
@@ -1119,8 +1298,9 @@ export interface SchemaTarget {
    * document's generation contract self-describing, so
    * {@link SchemaPipeline} reproduces a document deterministically
    * regardless of core's own default — for example, an `onExcessProperty`
-   * setting of `error` restores closed objects after rc.113 flipped that
-   * default open. See {@link StoreDocumentOptions.jsonSchema} for the
+   * setting of `"ignore"` reopens a document's objects, which
+   * {@link StoreDocument.fromSchema} closes by default. See
+   * {@link StoreDocumentOptions.jsonSchema} for that default and the
    * `includeAnnotationKey` gate this option is also subject to.
    */
   readonly jsonSchema?: Schema.ToJsonSchemaOptions;
@@ -1237,31 +1417,22 @@ interface SchemaValidatorShape {
 }
 declare const SchemaValidator_base: Context.ServiceClass<SchemaValidator, "@effected/schemastore/SchemaValidator", SchemaValidatorShape>;
 /**
- * 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).
- *
- * 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. It also registers the standard
- * ajv-formats vocabulary (`date-time`, `date`, `time`, `duration`, `uri`,
- * `uri-reference`, `uri-template`, `url`, `email`, `hostname`, `ipv4`,
- * `ipv6`, `regex`, `uuid`, `json-pointer`, `relative-json-pointer`, …), so a
- * published document can say "this string is an ISO-8601 instant" with a
- * `format` instead of falling back to a `pattern` plus a runtime filter;
- * an UNKNOWN format string remains a strict-mode rejection. The plugin's
- * `formatMaximum` / `formatMinimum` limit keywords are deliberately NOT
- * registered — `DocumentLint` answers those as unknown keywords, and the
- * two verdicts must not drift.
+ * The JSON Schema document validation contract — the engine SchemaStore's
+ * own gate is defined in terms of, as a service the pipeline requires in
+ * `R` and never owns.
+ *
+ * This package ships the contract and its doubles only: skip validation
+ * with {@link SchemaValidator.noop}, stub it with
+ * {@link SchemaValidator.layerTest}. The one real implementation is
+ * `@effected/schemastore-cli`'s `AjvValidator.layer` — ajv strict mode over
+ * the declared `KeywordFamilies` and the standard `ajv-formats`
+ * vocabulary — which the `schemastore` command composes for you and which
+ * that package also exports for a program that drives `SchemaPipeline`
+ * itself. Keeping the engine there keeps `ajv` out of every application that
+ * imports this package at runtime (to read a `HostedSchema`, say) and out of
+ * its bundle. `DocumentLint` is the owned, engine-free structural half of the
+ * validation story, and answers questions ajv does not (SchemaStore's own
+ * hygiene conventions).
  *
  * @example
  * ```ts
@@ -1273,38 +1444,20 @@ declare const SchemaValidator_base: Context.ServiceClass<SchemaValidator, "@effe
  *   return yield* validator.validate({ type: "object" });
  * });
  *
- * Effect.runPromise(Effect.provide(program, SchemaValidator.layer));
+ * // Provide the engine at the edge — the CLI does this for you:
+ * //   Effect.provide(program, AjvValidator.layer)   (from @effected/schemastore-cli)
+ * Effect.runPromise(Effect.provide(program, SchemaValidator.noop));
  * // => []
  * ```
  *
  * @public
  */
 export declare class SchemaValidator extends SchemaValidator_base {
-  /**
-   * The shipped ajv implementation — the default a consumer provides.
-   *
-   * `validate` checks the document against the Draft-07 meta-schema and
-   * then compiles it, reporting BOTH as {@link ValidationFinding} values:
-   * meta-schema failures keep ajv's structured `instancePath` and
-   * `keyword`, while a 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. The
-   * standard ajv-formats vocabulary is registered on every instance, so
-   * `format: "date-time"` (and the rest of the standard set) compiles under
-   * strict mode instead of being rejected as an unknown format.
-   */
-  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}.
+   * real engine, provide `AjvValidator.layer` from `@effected/schemastore-cli`.
    */
   static readonly noop: Layer.Layer<SchemaValidator>;
   /**
@@ -1529,15 +1682,18 @@ interface SchemaPipelineOptions {
  * 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
+ * `SchemaFile.layer` and an engine — `AjvValidator.layer` from
+ * `@effected/schemastore-cli`, which is what the `schemastore` command
+ * composes, or `SchemaValidator.noop` to skip validation — 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 { SchemaFile, SchemaPipeline, SchemaTarget } from "@effected/schemastore";
+ * import { AjvValidator } from "@effected/schemastore-cli";
  * import { NodeServices } from "@effect/platform-node";
  * import { Effect, Layer, Schema } from "effect";
  *
@@ -1550,7 +1706,7 @@ interface SchemaPipelineOptions {
  * ];
  *
  * const program = SchemaPipeline.run(targets).pipe(
- *   Effect.provide(Layer.mergeAll(SchemaFile.layer, SchemaValidator.layer)),
+ *   Effect.provide(Layer.mergeAll(SchemaFile.layer, AjvValidator.layer)),
  *   Effect.provide(NodeServices.layer),
  * );
  * ```
@@ -1631,41 +1787,155 @@ export declare class SchemaPipeline {
 //#region src/SchemastoreConfig.d.ts
 declare const ConfigBrand: unique symbol;
 /**
- * One catalog entry a `schemastore.config.ts` declares: the SchemaStore
- * `catalog.json` fields plus where to write the assembled entry. The entry's
- * `versions` and `url` are derived by {@link defineConfig} from every
- * versioned schema of the same `name`.
+ * The SchemaStore `catalog.json` fields a schema entry declares, minus
+ * `url`/`versions` — those are derived from the entry's `baseUrl`, `layout`
+ * and `versions`/`current` by {@link defineConfig}, so they cannot disagree
+ * with the schema's own identity.
  *
  * @public
  */
-interface CatalogConfig {
-  readonly name: string;
+interface CatalogInput {
+  /** The catalog description. */
   readonly description: string;
+  /** Glob patterns editors match files against; must be non-empty. */
   readonly fileMatch: ReadonlyArray<string>;
-  readonly baseUrl: string;
-  /** Where to write the assembled entry; relative paths are resolved by the loader against the config file's directory. */
-  readonly path: string;
 }
 /**
- * What a `schemastore.config.ts` hands to {@link defineConfig}: the schema
- * targets, an optional catalog block and an optional partial drift block.
+ * One schema a `schemastore.config.ts` declares, keyed by its own file base
+ * name in {@link SchemastoreConfigInput.schemas}. `$id`, the write `path` and
+ * every catalog URL are derived from `outputDir`, `baseUrl` (this entry's, or
+ * the config's default) and `layout` — never spelled out by hand.
+ *
+ * @public
+ */
+interface SchemaEntryInput {
+  /** The Effect Schema source the document is generated from. */
+  readonly schema: Schema.Constraint;
+  /**
+   * The schema's hosted identity, when the application already holds one
+   * (to derive its `$schema` URL from). Supplies `baseUrl`, `versions`,
+   * `current` and `layout`, which must then not be spelled here, and its
+   * `name` must equal this entry's key.
+   */
+  readonly hosted?: HostedSchema;
+  /**
+   * Every version label this schema advertises. Omit for an unversioned
+   * schema (`<name>.json`). An empty array is rejected — omit the field
+   * instead. Two labels that compare equal under
+   * {@link SchemaVersioning.Order} (`"1.2"` and `"1.2.0"`) are rejected as
+   * one version spelled twice.
+   */
+  readonly versions?: ReadonlyArray<string>;
+  /**
+   * Which of `versions` is the one generated at this entry's `path`/`$id`;
+   * the rest become {@link ResolvedSchema.frozen} files the CLI verifies
+   * but does not regenerate. Defaults to the newest label under
+   * {@link SchemaVersioning.Order}. Requires `versions`, and must name one
+   * of them.
+   */
+  readonly current?: string;
+  /**
+   * Whether a consumer already depends on this document at this label —
+   * forwarded to {@link (SchemaTarget:class).(make:1)}. Defaults to `false`.
+   */
+  readonly published?: boolean;
+  /**
+   * Where this schema is hosted: the literal `"schemastore"` (the only
+   * value that expands `$id` to {@link SCHEMASTORE_ID_BASE} and the catalog
+   * URL to {@link SCHEMASTORE_CATALOG_BASE}, and forces the `"flat"`
+   * layout) or an `https://` URL used as ONE base for both `$id` and the
+   * catalog URL. Falls back to {@link SchemastoreConfigInput.baseUrl} when
+   * omitted; an entry with neither is rejected.
+   */
+  readonly baseUrl?: string;
+  /**
+   * How a versioned document's path/URL nests relative to its base — see
+   * {@link SchemaLayout}. Defaults to `"versioned"` for a custom `baseUrl`,
+   * and is rejected outright under `baseUrl: "schemastore"`, which serves
+   * only the flat layout.
+   */
+  readonly layout?: SchemaLayout;
+  /**
+   * Whether a versioned file name carries the `-<version>` suffix
+   * (`<version>/<name>-<version>.json`, the default) or the version
+   * directory alone names it (`<version>/<name>.json`). `false` requires
+   * the `"versioned"` layout. Owned by `hosted` when that is given.
+   */
+  readonly appendVersion?: boolean;
+  /** Overrides {@link SchemastoreConfigInput.drift} for this schema. */
+  readonly drift?: DriftTolerance;
+  /**
+   * The catalog entry to assemble for this schema. Required under
+   * `baseUrl: "schemastore"` (every SchemaStore-hosted document is
+   * cataloged); optional under a custom host.
+   */
+  readonly catalog?: CatalogInput;
+  /** Forwarded to {@link (SchemaTarget:class).(make:1)}'s `jsonSchema`. */
+  readonly jsonSchema?: Schema.ToJsonSchemaOptions;
+  /** Forwarded to {@link (SchemaTarget:class).(make:1)}'s `rootAnnotations`. */
+  readonly rootAnnotations?: Readonly<Record<string, unknown>>;
+}
+/**
+ * What a `schemastore.config.ts` hands to {@link defineConfig}: a directory
+ * every derived path is written under, top-level defaults for `baseUrl` and
+ * `drift`, and the keyed set of schemas to derive.
  *
  * @public
  */
 interface SchemastoreConfigInput {
-  readonly schemas: ReadonlyArray<SchemaTarget>;
-  readonly catalog?: ReadonlyArray<CatalogConfig>;
-  readonly drift?: Partial<DriftOptions>;
+  /** The directory every derived `path` is written under; a trailing slash is trimmed. */
+  readonly outputDir: string;
+  /** The default {@link SchemaEntryInput.baseUrl} for an entry that declares none. */
+  readonly baseUrl?: string;
+  /** The default {@link SchemaEntryInput.drift} for an entry that declares none. Defaults to `"semantic"`. */
+  readonly drift?: DriftTolerance;
+  /** What a build does when it finds drift. Defaults to `"error"`. */
+  readonly onDrift?: OnDrift;
+  /** Where the assembled catalog is written. Defaults to `<outputDir>/catalog.json`. */
+  readonly catalogPath?: string;
+  /**
+   * The schemas to derive, keyed by file base name — the key IS the
+   * `name` every derived path and URL is built from, so it must be a
+   * simple file base name (no separators, no whitespace).
+   */
+  readonly schemas: Readonly<Record<string, SchemaEntryInput>>;
 }
 /**
- * A validated catalog declaration paired with the `CatalogEntry` assembled
- * from it.
+ * One version of a schema that is advertised (via `versions`) but not the
+ * one currently generated — a file the CLI verifies before any write (it
+ * exists, and its own `$id` is the derived one — the rest of its content is
+ * never compared), never regenerates.
  *
  * @public
  */
-interface CatalogTarget {
-  readonly config: CatalogConfig;
-  readonly entry: CatalogEntry;
+interface FrozenVersion {
+  /** The frozen version label. */
+  readonly version: SchemaVersion;
+  /** The path the frozen file lives at. */
+  readonly path: string;
+  /** The `$id` the frozen document must declare; differs from `url` only under `baseUrl: "schemastore"`. */
+  readonly $id: string;
+  /** The catalog URL the frozen file is hosted at. */
+  readonly url: string;
+}
+/**
+ * One `defineConfig` schema entry, resolved: the {@link (SchemaTarget:interface)} to
+ * generate, its frozen predecessor versions, its effective drift tolerance,
+ * and its assembled catalog entry, if any.
+ *
+ * @public
+ */
+interface ResolvedSchema {
+  /** The schema's key in {@link SchemastoreConfigInput.schemas}. */
+  readonly name: string;
+  /** The target to generate at the current version (or the sole, unversioned target). */
+  readonly target: SchemaTarget;
+  /** Every OTHER advertised version, as a frozen file to verify. */
+  readonly frozen: ReadonlyArray<FrozenVersion>;
+  /** This entry's effective drift tolerance, after falling back to the config default. */
+  readonly drift: DriftTolerance;
+  /** The assembled catalog entry, when {@link SchemaEntryInput.catalog} was given. */
+  readonly catalog?: CatalogEntry;
 }
 /**
  * The validated, defaults-filled config {@link defineConfig} answers and the
@@ -1675,23 +1945,47 @@ interface CatalogTarget {
  */
 interface SchemastoreConfig {
   readonly [ConfigBrand]: true;
-  readonly schemas: ReadonlyArray<SchemaTarget>;
-  readonly catalog: ReadonlyArray<CatalogTarget>;
-  readonly drift: DriftOptions;
+  /** The directory every derived `path` is written under, trailing slash trimmed. */
+  readonly outputDir: string;
+  /** What a build does when it finds drift. */
+  readonly onDrift: OnDrift;
+  /** Where the assembled catalog is written. */
+  readonly catalogPath: string;
+  /** Every schema, resolved. */
+  readonly schemas: ReadonlyArray<ResolvedSchema>;
 }
 /**
  * Validate and assemble a `schemastore.config.ts` value.
  *
  * @remarks
- * Pure: no IO, no Effect. Identity-with-validation over the input, filling
- * drift defaults, deriving each catalog entry's `versions` from EVERY
- * versioned schema of that name (published or not — the entry is what gets
- * submitted to become published), and branding the result so a loader can
- * recognise a config module's default export. Throws a plain `Error` on a
- * bad input; the CLI wraps it into its typed config-load error. Rejects an
- * output `path` declared twice across schemas and catalog entries, compared
- * after a lexical normalisation (`./`, `..`, trailing `/`); the CLI's loader
- * re-checks on the resolved absolute paths.
+ * Pure: no IO, no Effect. `$id`, the write `path` and every catalog URL are
+ * derived from ONE layout (`outputDir`, `baseUrl` and `layout`) so they
+ * cannot disagree with each other. `versions` names every label a schema
+ * advertises; `current` (default: the newest under
+ * {@link SchemaVersioning.Order}) is the one generated at `target`, and every
+ * other label becomes a {@link FrozenVersion} the CLI verifies but does not
+ * regenerate. `baseUrl: "schemastore"` expands to
+ * {@link SCHEMASTORE_ID_BASE} for `$id` and {@link SCHEMASTORE_CATALOG_BASE}
+ * for the catalog URL, forcing the `"flat"` layout; any other `baseUrl` is
+ * used as one base for both, defaulting to the `"versioned"` layout.
+ *
+ * Throws a plain `Error` (never a raw `TypeError`) on every malformed
+ * input. The shape is decoded once per level with a `Schema.Struct`
+ * (`errors: "all"`, so every issue on an entry is reported at once, and
+ * `onExcessProperty: "error"`, so a typo'd key is named rather than
+ * dropped); the message is `defineConfig: schema "<name>" ` followed by the
+ * decode issues (`Expected string at ["baseUrl"]`). After a shape-clean
+ * decode the cross-field rules run: the entry's identity — its
+ * {@link HostedSchema}, or one built from `baseUrl`/`versions`/`current`/
+ * `layout` and the config default — is validated by `HostedSchema` itself
+ * (a `hosted` entry must be keyed by `hosted.name` and must not spell those
+ * four fields beside it); a schema key must be a simple file base name; a
+ * `catalog` is required under `baseUrl: "schemastore"`; an empty `schemas`
+ * record is rejected; and an output path (a target, a frozen file, or the
+ * catalog path) declared twice is rejected after a lexical normalisation
+ * (`./`, `..`, trailing `/`) — the CLI's loader re-checks on the resolved
+ * absolute paths. Branding the result lets a loader recognise a config
+ * module's default export via {@link isSchemastoreConfig}.
  *
  * @public
  */
@@ -1704,5 +1998,5 @@ export declare const defineConfig: (input: SchemastoreConfigInput) => Schemastor
  */
 export declare const isSchemastoreConfig: (value: unknown) => value is SchemastoreConfig;
 //#endregion
-export type { CanonicalJsonError, CanonicalJsonOptions, CatalogConfig, CatalogTarget, CatalogUrls, CheckResult, ContractChangePolicy, DriftOptions, DriftTolerance, DriftVerdict, OnDrift, PipelineCheckResult, PipelineResult, SchemaChange, SchemaFileShape, SchemaPipelineOptions, SchemaValidatorOptions, SchemaValidatorShape, SchemaWriteOptions, SchemastoreConfig, SchemastoreConfigInput, StoreDocumentOptions, WriteChange, WriteOutcome, WriteResult };
+export type { CanonicalJsonError, CanonicalJsonOptions, CatalogInput, CatalogUrls, CheckResult, ContractChangePolicy, CustomHostedSchemaInput, DriftOptions, DriftTolerance, DriftVerdict, FrozenVersion, GitHubHostedSchemaInput, HostedSchemaVersionsInput, OnDrift, PipelineCheckResult, PipelineResult, ResolvedSchema, SchemaChange, SchemaEntryInput, SchemaFileShape, SchemaLayout, SchemaPipelineOptions, SchemaValidatorOptions, SchemaValidatorShape, SchemaWriteOptions, SchemastoreConfig, SchemastoreConfigInput, StoreDocumentOptions, WriteChange, WriteOutcome, WriteResult };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -5,11 +5,12 @@ import { KeywordFamilies } from "./KeywordFamilies.js";
 import { DocumentDiff } from "./DocumentDiff.js";
 import { DocumentLint, DocumentLintFinding } from "./DocumentLint.js";
 import { DriftPolicy } from "./DriftPolicy.js";
+import { HostedSchema, SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE } from "./HostedSchema.js";
 import { SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError } from "./SchemaFile.js";
 import { SchemaValidator, SchemaValidatorError, ValidationFinding } from "./SchemaValidator.js";
 import { DRAFT_07_META_SCHEMA, SchemaConversionError, StoreDocument, UndeclaredAnnotationKeyError } from "./StoreDocument.js";
 import { ContractChangeTarget, PipelineFinding, SchemaContractChangeError, SchemaGateError, SchemaPipeline } from "./SchemaPipeline.js";
-import { defineConfig, isSchemastoreConfig } from "./SchemastoreConfig.js";
 import { SchemaTarget } from "./SchemaTarget.js";
+import { defineConfig, isSchemastoreConfig } from "./SchemastoreConfig.js";
 
-export { CanonicalJson, CatalogEntry, CatalogLintFinding, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, DriftPolicy, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, PipelineFinding, SchemaContractChangeError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError, SchemaGateError, SchemaPipeline, SchemaTarget, SchemaValidator, SchemaValidatorError, SchemaVersion, SchemaVersioning, StoreDocument, UndeclaredAnnotationKeyError, ValidationFinding, defineConfig, isSchemastoreConfig };
+export { CanonicalJson, CatalogEntry, CatalogLintFinding, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, DriftPolicy, HostedSchema, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, PipelineFinding, SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE, SchemaContractChangeError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError, SchemaGateError, SchemaPipeline, SchemaTarget, SchemaValidator, SchemaValidatorError, SchemaVersion, SchemaVersioning, StoreDocument, UndeclaredAnnotationKeyError, ValidationFinding, defineConfig, isSchemastoreConfig };