@yanlinglabs/winter-provider-catalog 0.0.1

package/README.md

@@ -0,0 +1,46 @@
+# `@yanlinglabs/winter-provider-catalog`
+
+Winter's provider and model catalog as inert, validated DATA: 165 provider rows and 604 model rows
+with their endpoints, auth kinds, pricing evidence, admission tier and provenance, plus the validator
+and the vocabularies the JSON Schema restates.
+
+No network, no filesystem, no Bun API — the catalog is a bundled JSON module import, which is what
+lets it be decoded anywhere. `PROVENANCE.md` records where every row came from and under what
+evidence; `bun run provenance:tiers -- --check` regenerates its census from the shipped data.
+
+## Install
+
+This package is published to **two registries**, and which one you want depends on who you are.
+
+### From public npm (anyone)
+
+```sh
+npm install @yanlinglabs/winter-provider-catalog
+```
+
+Nothing else is needed: the `@yanlinglabs` scope is public on npm.
+
+### From GitHub Packages (the `yanlingLabs` org)
+
+GitHub Packages needs the scope pointed at it and an authenticated read, even for a public package.
+In your project's `.npmrc`:
+
+```
+@yanlinglabs:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+…with `GITHUB_TOKEN` in the environment — a personal access token carrying `read:packages`, never a
+literal in the file. Then `npm install @yanlinglabs/winter-provider-catalog` as usual.
+
+**The published packages contain COMPILED OUTPUT ONLY.** Each tarball ships `dist/` — the bundled
+JavaScript a consumer imports and the `.d.ts` declarations their type-checker reads — plus its data
+files, `README.md` and `LICENSE`. It does **not** ship `src/`: the TypeScript sources live at
+<https://github.com/yanlingLabs/winter-agent-sdk>, which is where to read them, file an issue, or send
+a patch.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE), which ships in the published tarball.
+
+Third-party attribution for the upstream catalog data this package derives from is in [`NOTICE`](./NOTICE), which ships in the tarball beside this file.

package/UPSTREAM.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "GENERATED — do not edit. The pin `scripts/provider-catalog.ts` stamps onto the merged catalog; the extractor's INPUT pin lives in third_party/omniroute-provider-source/UPSTREAM.json. `tagObject` is the annotated tag's own object id and `commit` is that tag PEELED — they are different objects, and recording only one of them would not be a pin.",
+  "upstream": {
+    "tag": "v3.8.50",
+    "tagObject": "6f5d4e00e817bc01b2ac16fdd66db3840c296416",
+    "commit": "5458026c216f77a3da68ea49152dc33470cfe2cb",
+    "extractorVersion": "winter.1",
+    "overlayVersion": "1"
+  }
+}

package/dist/extract/fetch.d.ts

@@ -0,0 +1,62 @@
+/** The recorded pin. All four fields are checked against the fetched clone before anything is read. */
+export interface UpstreamPin {
+    repository: string;
+    tag: string;
+    /** The annotated tag's OWN object id. */
+    tagObject: string;
+    /** The tag peeled to a commit — this is what the catalog records as `upstream.commit`. */
+    commit: string;
+}
+/** One allowlist path entry. `pattern` is a git sparse-checkout pattern rooted at the repository. */
+export interface AllowlistPath {
+    pattern: string;
+    role: "extract" | "claim" | "notice";
+    why: string;
+}
+export interface MaterializedFile {
+    /** Repository-relative, `/`-separated. */
+    path: string;
+    /** git's own blob id — authoritative, and directly comparable with `git ls-tree` upstream. */
+    blobId: string;
+    /** sha256 of the materialized bytes, so a manifest entry is verifiable without git. */
+    sha256: string;
+    bytes: number;
+    role: AllowlistPath["role"];
+    /** The allowlist pattern that admitted this path. */
+    admittedBy: string;
+}
+export interface FetchResult {
+    /** Absolute path of the checkout root. Valid until `cleanup()`. */
+    root: string;
+    commit: string;
+    tagObject: string;
+    files: MaterializedFile[];
+    read(path: string): string;
+    cleanup(): void;
+}
+/** Thrown for every refusal in this module. A pin/boundary failure is never a warning. */
+export declare class UpstreamFetchError extends Error {
+    constructor(message: string);
+}
+/**
+ * Translate one git sparse-checkout `--no-cone` pattern into a matcher.
+ *
+ * Deliberately supports only the subset the allowlist actually uses — a leading `/` anchor,
+ * `**` (any depth) and `*` (one segment) — and rejects anything else, because a pattern this
+ * function silently mis-parses is a boundary hole that looks like a boundary.
+ */
+export declare function compilePathPattern(pattern: string): (path: string) => boolean;
+export interface FetchOptions {
+    /** Where the scratch checkout goes. Defaults to a fresh mkdtemp under the OS temp dir. */
+    parentDir?: string;
+    /** Overrides `pin.repository` — the tests point this at a `file://` fixture repository. */
+    repositoryOverride?: string;
+}
+/**
+ * Clone the pinned tag, materialize exactly the allowlisted paths, verify, and hash.
+ *
+ * The caller MUST call `cleanup()` (the sync script does it in a `finally`): the checkout is a
+ * scratch directory outside the repository and nothing but the generated JSON and the two upstream
+ * notice files ever survives it.
+ */
+export declare function fetchUpstream(pin: UpstreamPin, paths: AllowlistPath[], options?: FetchOptions): FetchResult;

package/dist/extract/ledgers.d.ts

@@ -0,0 +1,113 @@
+import type { MaterializedFile, UpstreamPin } from "./fetch.js";
+export interface DenominatorReport {
+    /** Distinct upstream ids across every product-catalog category file. */
+    catalogueUnion: number;
+    /** Per-category distinct-id counts, in the order WS-13 §1's table lists them. */
+    byCategory: Array<{
+        category: string;
+        count: number;
+    }>;
+    /** Ids appearing in more than one category file — each would be double-counted by a naive sum. */
+    duplicatedAcrossCategories: string[];
+    /** Naive sum of per-category counts, i.e. what double-counting would produce. */
+    categorySum: number;
+    /** Keys of the backend `REGISTRY` map — the EXECUTABLE catalog, always smaller than the product one. */
+    registryEntries: number;
+    /**
+     * How many of those keys the literal walker could actually RESOLVE to an entry object.
+     *
+     * Reported separately and deliberately: many upstream entries are built by a helper call
+     * (`buildOpenAiCompatibleRegistryEntry({…})`), which the extractor rejects as an executable value,
+     * so their bindings do not exist. Folding the two numbers into one would report the extractor's
+     * own blind spot as an upstream fact — which is exactly the kind of quiet denominator error this
+     * report exists to expose.
+     */
+    registryEntriesResolved: number;
+    /** Catalogued ids with no backend registry entry. */
+    catalogueWithoutRegistry: number;
+    /** Registry ids with no product-catalog row. */
+    registryWithoutCatalogue: number;
+    /** What upstream itself CLAIMS, per claim source. */
+    claims: Array<{
+        sourcePath: string;
+        claimed: number | undefined;
+        note: string;
+    }>;
+    /** Human-readable summary, embedded verbatim in PROVENANCE.md. */
+    summary: string;
+}
+export interface DenominatorInput {
+    /** category name -> the distinct upstream ids it contains. */
+    byCategory: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Every key of the backend `REGISTRY` map, read from the object's TEXT (never from resolved values). */
+    registryIds: ReadonlySet<string>;
+    /** The subset whose entry object the literal walker resolved. */
+    registryIdsResolved: ReadonlySet<string>;
+    /** Claim source path -> its raw text, scanned for the headline provider count. */
+    claimSources: ReadonlyArray<{
+        sourcePath: string;
+        text: string;
+    }>;
+}
+/**
+ * Pull upstream's own headline provider count out of a claim source.
+ *
+ * Two spellings at the pin: the generated reference says "Total providers: **352**", the README says
+ * "352 AI providers". Both are matched, and a source that states neither returns `undefined` rather
+ * than a zero — "we could not find a claim" and "upstream claims none" are different facts.
+ */
+export declare function findClaimedProviderCount(text: string): number | undefined;
+export declare function computeDenominator(input: DenominatorInput): DenominatorReport;
+export interface ExtractionManifest {
+    $comment: string;
+    upstream: UpstreamPin & {
+        packageVersion?: string;
+    };
+    extractorVersion: string;
+    generatedFrom: string;
+    /** Files COPIED into this repository (upstream licence/notices), with their provenance. */
+    copiedFiles: Array<{
+        upstreamPath: string;
+        localPath: string;
+        blobId: string;
+        sha256: string;
+        bytes: number;
+        licence: string;
+        modifications: "none";
+    }>;
+    /** Files READ during extraction and deliberately NOT copied. */
+    readOnlyFiles: Array<{
+        path: string;
+        blobId: string;
+        sha256: string;
+        bytes: number;
+        role: string;
+        admittedBy: string;
+    }>;
+    outOfAllowlistImports: string[];
+}
+export interface ManifestInput {
+    pin: UpstreamPin & {
+        packageVersion?: string;
+    };
+    extractorVersion: string;
+    files: readonly MaterializedFile[];
+    /** upstream path -> where it was copied to inside this repository. */
+    copiedTo: ReadonlyMap<string, string>;
+    outOfAllowlistImports: readonly string[];
+}
+export declare function buildExtractionManifest(input: ManifestInput): ExtractionManifest;
+export type ProvenanceClass = "copied-verbatim" | "mechanically-normalized" | "official-doc-derived" | "live-probe-proven" | "local-override";
+export interface FieldProvenance {
+    field: string;
+    provenance: ProvenanceClass;
+    note: string;
+}
+/**
+ * The per-field classification report §6 asks for, as DATA.
+ *
+ * PROVENANCE.md renders this table rather than restating it in prose, because a hand-written
+ * provenance table is exactly the document that goes stale the first time the mapper changes and
+ * nobody notices — and a stale provenance claim is worse than none.
+ */
+export declare const FIELD_PROVENANCE: readonly FieldProvenance[];

package/dist/extract/literal-extractor.d.ts

@@ -0,0 +1,94 @@
+export type LiteralValue = string | number | boolean | null | LiteralValue[] | {
+    [key: string]: LiteralValue;
+};
+/**
+ * Why something did not reach the catalog. The FIELD/VALUE classes are this module's; the CATEGORY
+ * and CURATION classes are `ledgers.ts`'s, and both live in one union so the committed ledger has a
+ * single closed vocabulary a reviewer can diff across upstream bumps.
+ */
+export type ExclusionClass = "executable-value" | "dynamic-expression" | "env-read" | "identity-header" | "url-builder" | "credential-material" | "unresolved-reference" | "unsupported-shape" | "category-no-auth" | "category-oauth" | "category-web-cookie" | "category-search" | "category-audio" | "category-upstream-proxy" | "category-cloud-agent" | "category-system" | "category-local-live-discovery" | "not-allowlisted" | "no-registry-entry" | "duplicate-id" | "unrepresentable-protocol"
+/**
+ * NOT an exclusion. A row that DID reach the catalog, carrying a reviewed, recorded deviation from
+ * what the pinned tree literally says (a corrected wire id, an adapter the protocol does not imply,
+ * a per-row status). It shares the ledger with the exclusions because the ledger's job is "every
+ * place the catalog and its source differ, with the reason" — and filing a deliberate normalization
+ * under `unrepresentable-protocol` made the ledger's own counts lie about what was dropped.
+ */
+ | "reviewed-normalization"
+/** A row excluded because it is not a language model at all (WS-13 §4: `tts`/`stt`/media rows never feed the worker-model picker). */
+ | "out-of-scope";
+export interface Rejection {
+    scope: "module" | "provider" | "model" | "field";
+    /** The upstream provider id this rejection belongs to, or `""` for a module-level one. */
+    upstreamId: string;
+    /** Dotted location inside the module, e.g. `geminiProvider.oauth`. */
+    path: string;
+    sourcePath: string;
+    reason: string;
+    exclusionClass: ExclusionClass;
+}
+export interface ExtractOptions {
+    /**
+     * Exported literals from other ALLOWLISTED modules, keyed `<sourcePath>#<exportName>` and
+     * `#<exportName>` (the latter is the "any allowlisted module" fallback used when an import
+     * specifier resolves to a materialized file whose own exports are already known).
+     */
+    externals?: ReadonlyMap<string, LiteralValue>;
+    /** Every repository-relative path that was materialized, so an out-of-allowlist import is visible. */
+    materializedPaths?: ReadonlySet<string>;
+}
+export interface ModuleLiterals {
+    sourcePath: string;
+    /** Top-level `const` bindings whose initializer was fully accepted. */
+    values: Map<string, LiteralValue>;
+    rejections: Rejection[];
+    /** Import specifiers naming a module outside the materialized allowlist. */
+    outOfAllowlistImports: string[];
+    /** Imported name -> the module specifier it came from, for `unresolved-reference` reasons. */
+    importOrigins: Map<string, string>;
+}
+/**
+ * Resolve a relative import specifier against a repository-relative source path.
+ *
+ * Upstream mixes explicit `./shared.ts` specifiers with extensionless `./gateways` ones, so an
+ * `exists` predicate is consulted for the two implicit spellings. Without it every extensionless
+ * import inside the allowlist reads as OUT of the allowlist — a false boundary alarm that would
+ * bury the real ones.
+ */
+export declare function resolveRelativeSpecifier(sourcePath: string, specifier: string, exists?: (path: string) => boolean): string | undefined;
+/**
+ * Parse one module and extract its accepted top-level literal bindings.
+ *
+ * Never throws on hostile input: a syntactically broken file yields no values and a module-scope
+ * rejection. Depth-bounded so a pathological nesting cannot overflow the stack.
+ */
+export declare function extractModuleLiterals(sourcePath: string, text: string, options?: ExtractOptions): ModuleLiterals;
+/**
+ * Extract a whole materialized set, resolving cross-module identifier references between
+ * ALLOWLISTED files only.
+ *
+ * ITERATES TO A FIXPOINT rather than running a fixed number of passes, because upstream's import
+ * graph is neither topologically ordered nor shallow. The real chain at the pin is three deep and
+ * runs BACKWARDS against filename order:
+ *
+ *     open-sse/config/providers/index.ts          (REGISTRY -> each provider identifier)
+ *       <- registry/openai/index.ts               (a model spreads GPT_5_6_API_CAPABILITIES)
+ *         <- shared.ts                            (where that constant is declared)
+ *
+ * `index.ts` sorts FIRST and `shared.ts` LAST, so a two-pass version resolved the leaf entries but
+ * handed `index.ts` the stale first-pass copies — and the whole GPT-5.6 family silently lost its
+ * context window, modalities and Responses endpoint while every row still looked plausible. A
+ * fixpoint has no such off-by-one: it stops when a pass adds nothing, and the pass budget exists
+ * only so a pathological graph terminates rather than looping.
+ *
+ * Values accumulate into ONE map that later files in the SAME pass can already read, so a forward
+ * dependency costs no extra pass at all.
+ */
+export declare function extractAll(files: ReadonlyArray<{
+    path: string;
+    text: string;
+}>): {
+    modules: Map<string, ModuleLiterals>;
+    exports: Map<string, LiteralValue>;
+    passes: number;
+};

package/dist/extract/merge.d.ts

@@ -0,0 +1,213 @@
+import type { AdmissionTier, ModelFamilyDescriptor, ProviderProtocol, WinterCatalog, WinterModelDescriptor, WinterProviderDescriptor } from "../types.js";
+import type { ExclusionClass, LiteralValue, Rejection } from "./literal-extractor.js";
+export interface AllowlistProviderRow {
+    upstreamId: string;
+    winterId: string;
+    expectedCategory: string;
+    /**
+     * The `status` every extracted model of this provider starts at. Absent means `candidate`.
+     *
+     * R6-16 puts the native-cloud families in the catalog as `experimental`; nothing here can ever
+     * reach `supported`, which requires the behavioural corpus (WS-13 §13).
+     */
+    initialModelStatus?: "candidate" | "experimental";
+    /**
+     * The display name this provider's row must carry, when the product catalog's own `name` would be
+     * AMBIGUOUS rather than merely different.
+     *
+     * R6b-5 puts a vendor's two documented dialects on two rows, and the upstream product catalog has
+     * ONE name for the vendor — so `zai` and `zai-anthropic` both read "Z.AI" in a picker, which is a
+     * row a user cannot choose between. The override is a reviewed allowlist edit like `winterId` and
+     * `adapterIdOverride`, and it is RECORDED in the ledger; it is not a licence to rename providers
+     * for taste.
+     */
+    displayNameOverride?: string;
+    /**
+     * The adapter this provider's rows must name, when it is NOT the one its protocol implies.
+     *
+     * Vertex shares the GenerateContent dialect with the Gemini API, so deriving the adapter from the
+     * protocol named `winter.google-generate-content` — and a registry resolves an adapter BY ID, so a
+     * Vertex session would have been served by the Gemini API adapter with no location-scoped URL and
+     * no ADC credential. A protocol is not an adapter.
+     */
+    adapterIdOverride?: string;
+    risk: {
+        class: "approved" | "review-required" | "blocked";
+        reasons: string[];
+    };
+    /**
+     * WS-13b §1: how the vendor charges for the credential Winter uses. COPIED VERBATIM onto the
+     * generated row — the extractor never derives it, because nothing in the pinned upstream tree
+     * states it and a derivation would be Winter guessing at a billing fact.
+     */
+    pricingBasis: "token" | "subscription" | "free";
+    /**
+     * WS-13b §1 (D21): the documented third-party path this row ships through, with its citation.
+     * Also copied verbatim, and REQUIRED: an allowlist entry missing it fails the run rather than
+     * producing a row whose admission nobody can check — see step (0) at the top of
+     * `buildUpstreamLayer`, which refuses before anything is classified.
+     */
+    admission: {
+        basis: "api-key" | "oauth-documented" | "keyless-documented" | "local" | "cloud-credential";
+        citation: string;
+        tier: AdmissionTier;
+    };
+    /**
+     * WS-13b §7/§8.4 (fix-wave R-FW-2): the vendor's own second identity field, copied verbatim like
+     * the two above. Absent for every allowlist row today -- only a vendor that DOCUMENTS such a field
+     * gets one, and none of the extracted entries does.
+     */
+    identityHeaders?: Record<string, string>;
+}
+/** A hand-reviewed, per-model deviation from what the pinned upstream tree says. Always recorded. */
+export interface ModelOverride {
+    /** Corrects a wire id upstream spells differently from the provider's own documentation. */
+    id?: string;
+    /** Keeps the row OUT of the catalog entirely (WS-13 §4: a non-`llm` row never reaches the worker-model picker). */
+    exclude?: boolean;
+    /** Overrides the provider's `initialModelStatus` for this one row. */
+    status?: "candidate" | "experimental";
+    why: string;
+}
+export interface CategoryDisposition {
+    disposition: "blocked" | "candidate-pool" | "winter-owned";
+    exclusionClass: ExclusionClass;
+    reason: string;
+}
+export interface Allowlist {
+    allowlistVersion: number;
+    paths: Array<{
+        pattern: string;
+        role: "extract" | "claim" | "notice";
+        why: string;
+    }>;
+    providers: AllowlistProviderRow[];
+    categoryDispositions: Record<string, CategoryDisposition>;
+    /** providerId -> upstream model id -> a hand-reviewed override. Every field is optional but `why`. */
+    modelOverrides?: Record<string, Record<string, ModelOverride>>;
+    blocked: Array<{
+        upstreamId: string;
+        reason: string;
+    }>;
+    importBoundary: {
+        resolveIdentifiersWithin: string;
+        failOnUnresolvedFields: string[];
+    };
+}
+/**
+ * Upstream `format` -> the path THAT FORMAT'S adapters append to a base URL.
+ *
+ * Removing this suffix from upstream's `baseUrl` is how the mapper reaches the API ROOT a
+ * `defaultEndpoints.api` must carry. See the long note at the `baseUrl` block in
+ * `buildUpstreamLayer` for why a consumed row cannot hold the verbatim path, and why this is the
+ * only transformation permitted (never a trim to an origin).
+ *
+ * Keyed on the upstream FORMAT, not on the Winter protocol or adapter: the suffix is a fact about
+ * the URL as upstream wrote it. `deepseek` is `format: "openai-responses"` at
+ * `https://api.deepseek.com/responses`; `openai` is `format: "openai"` at
+ * `https://api.openai.com/v1/chat/completions` even though its allowlist row overrides the adapter
+ * to Responses. Both strip their own format's suffix and land on the root their adapter expects.
+ *
+ * Exported so a test can assert the strip reproduces the five hand-authored overlay endpoints.
+ */
+export declare const FORMAT_ENDPOINT_SUFFIX: Readonly<Record<string, string>>;
+/**
+ * Adapter id -> the ONE protocol it speaks. The reverse of `PROTOCOL_TO_ADAPTER`, plus the adapters
+ * a protocol does not imply.
+ *
+ * Exported because the cross-layer gate must key on the ADAPTER, not on the provider's `protocols`
+ * list: resolution hands a model to `provider.adapterId` and nothing reads `protocols` at all, so a
+ * gate that consulted the list passed a responses-only model under a provider that merely DECLARED
+ * `openai-responses` while its adapter spoke Chat Completions.
+ */
+export declare const ADAPTER_PROTOCOL: Readonly<Record<string, ProviderProtocol>>;
+/**
+ * A model row as a LAYER carries it: everything a finished row has EXCEPT the two derived family
+ * fields (WS-13c §1).
+ *
+ * The two are stamped once, at assembly, by `stampFamilyFields` — and `stampFamilyFields` treats a
+ * value already on the row as an OVERLAY OVERRIDE it must never overwrite. So a layer that pre-filled
+ * them would freeze whatever it guessed: an upstream layer stamped with no families at hand would
+ * write `modelFamily: "other"` onto 540 rows, and the merge would then honour that "override"
+ * forever. The layer therefore does not carry them, and the committed `upstream-layer.json` is
+ * correct exactly as it stands.
+ */
+export type UnstampedModelDescriptor = Omit<WinterModelDescriptor, "modelFamily" | "canonicalModelId">;
+export interface UpstreamLayer {
+    $comment: string;
+    providers: WinterProviderDescriptor[];
+    models: UnstampedModelDescriptor[];
+    rejections: LedgerRejection[];
+}
+/** A rejection row as it is COMMITTED — the extractor's `Rejection` plus its upstream identity. */
+export interface LedgerRejection {
+    upstreamId: string;
+    scope: Rejection["scope"];
+    exclusionClass: ExclusionClass;
+    path: string;
+    sourcePath: string;
+    reason: string;
+}
+export interface BuildUpstreamLayerInput {
+    allowlist: Allowlist;
+    /** Upstream provider id -> its `RegistryEntry` literal. */
+    registry: ReadonlyMap<string, LiteralValue>;
+    /** Upstream provider id -> its product-catalog category (`apikey`, `web-cookie`, …). */
+    categories: ReadonlyMap<string, {
+        category: string;
+        sourcePath: string;
+        row: LiteralValue;
+    }>;
+    /** Upstream provider id -> the repository-relative path its registry entry was read from. */
+    registrySourcePaths: ReadonlyMap<string, string>;
+    commit: string;
+    /** ISO-8601 instant stamped onto every piece of extracted evidence. */
+    observedAt: string;
+    /** Field/value rejections the extractor already produced, keyed by source path. */
+    moduleRejections: readonly Rejection[];
+}
+export declare class ExtractionRefusal extends Error {
+    constructor(message: string);
+}
+/**
+ * Build the upstream layer from the materialized literals.
+ *
+ * Order of operations matters and is deliberate:
+ *  1. every upstream id in the product catalog is CLASSIFIED (category -> disposition);
+ *  2. an allowlisted id whose category is not `candidate-pool` FAILS the run — that is WS-13 §3
+ *     step 7's blocked class transition, and it is the only reason the allowlist is checked against
+ *     the catalog rather than simply trusted;
+ *  3. surviving ids are mapped, with unknown format/auth/executor values failing the row;
+ *  4. everything else lands in the ledger with a class.
+ */
+export declare function buildUpstreamLayer(input: BuildUpstreamLayerInput): UpstreamLayer;
+/** Total, stable rejection ordering: a ledger diff between two upstream bumps must show CHANGES, not churn. */
+export declare function compareRejections(a: LedgerRejection, b: LedgerRejection): number;
+/** The overlay files a re-sync must NEVER write. Exported so the sync script's own guard and its test read the same list. */
+export declare const OVERLAY_FILES: readonly ["overlay/providers.json", "overlay/models.json", "overlay/families.json"];
+/**
+ * The overlay-wins merge, mirroring `scripts/provider-catalog.ts`.
+ *
+ * Used to VALIDATE a layer before the frozen script writes anything — never to write the committed
+ * catalog. Row-level, not field-level: WS-13 §7's rule is that upstream never overwrites overlay
+ * evidence, and a field-level merge would do exactly that for every field the overlay leaves out.
+ *
+ * WS-13c: the family stamp happens HERE and in the script, through the ONE `stampFamilyFields` both
+ * call — a second implementation of "which family is this" would make the standalone gate and the
+ * committed catalog disagree about a row while both reported success. `pipeline.test.ts` pins the
+ * two assemblers byte-identical on the real layers, which is what keeps the mirroring honest.
+ *
+ * `families` defaults to EMPTY, and that default is what the upstream layer's standalone check
+ * uses: the layer alone has none of the overlay rows the real slots point at, so validating it
+ * against the real families would fail `slot-model-missing` on rows that are present in the merged
+ * catalog and only there. With no families every row stamps `other`, which the validator accepts —
+ * the standalone gate is about the LAYER's own shape, and family assignment is the merged catalog's
+ * own gate (`bun run provider:catalog --check` plus the integrity suite).
+ */
+export declare function mergeLayers(upstream: {
+    providers: WinterProviderDescriptor[];
+    models: UnstampedModelDescriptor[];
+}, overlay: {
+    providers: WinterProviderDescriptor[];
+    models: UnstampedModelDescriptor[];
+}, pin: WinterCatalog["upstream"], families?: readonly ModelFamilyDescriptor[]): WinterCatalog;

package/dist/families.d.ts

@@ -0,0 +1,55 @@
+import type { FamilySlot, ModelFamilyDescriptor, WinterCatalog, WinterModelDescriptor } from "./types.js";
+export declare const SLOT_NAME_RE: RegExp;
+export declare const FAMILY_ID_RE: RegExp;
+export declare const CLAUDE_FAMILY_ID = "claude";
+export declare const OTHER_FAMILY_ID = "other";
+/** D25: reserved to the `claude` family, in the pinned order. */
+export declare const CLAUDE_RESERVED_SLOT_NAMES: readonly string[];
+/** "$10", "10 USD", "€2", "£1", "10 dollars" — pricing lives on rows, never in a slot description. */
+export declare const CURRENCY_RE: RegExp;
+/** The vendor's model identity with the provider's spelling removed (WS-13c §1, R13c-2). Deterministic; a per-row overlay `canonicalModelId` overrides it. */
+export declare function canonicalModelIdOf(upstreamId: string): string;
+export declare function familyIdOf(canonicalModelId: string, families: readonly ModelFamilyDescriptor[]): string;
+export declare function stampFamilyFields<T extends {
+    upstreamId: string;
+    canonicalModelId?: string;
+    modelFamily?: string;
+}>(rows: readonly T[], families: readonly ModelFamilyDescriptor[]): Array<T & {
+    canonicalModelId: string;
+    modelFamily: string;
+}>;
+export type SlotNameResolution = {
+    kind: "slot";
+    family: ModelFamilyDescriptor;
+    slot: FamilySlot;
+    advertised: boolean;
+} | {
+    kind: "ambiguous";
+    name: string;
+    candidates: string[];
+} | {
+    kind: "unknown";
+    name: string;
+};
+/** WS-13c §3 acceptance: active set first; the Claude names always into `claude`; a unique foreign name; else ambiguous/unknown. */
+export declare function resolveSlotName(name: string, activeFamilyId: string | undefined, families: readonly ModelFamilyDescriptor[]): SlotNameResolution;
+export declare function familyOfModelKey(catalog: WinterCatalog, modelKey: string): ModelFamilyDescriptor | undefined;
+/**
+ * Can this row serve a slot at all? (WS-13c §4 step 1.)
+ *
+ * ONE predicate, deliberately, and it is what fix round 1's I-3 closed: the validator's
+ * `slot-model-missing` check and `rowsForCanonicalId` had drifted into two answers — the validator
+ * asked only about `status`, the resolver also required a chat/responses endpoint. A slot whose only
+ * rows were `endpoints: ["embeddings"]` therefore VALIDATED and resolved to nothing, which makes the
+ * natural inference "the catalog validated, so every slot has a candidate row" false in exactly the
+ * place a lane relies on it.
+ *
+ * Structurally typed rather than taking a `WinterModelDescriptor`, because the validator's caller
+ * holds `unknown` JSON it has already shape-checked, not a narrowed row.
+ */
+export declare function isSlotServableRow(row: {
+    status: string;
+    endpoints: readonly string[];
+}): boolean;
+/** Candidate rows for a slot (WS-13c §4 step 1). The SAME predicate `validateCatalog` refuses a slot on. */
+export declare function rowsForCanonicalId(catalog: WinterCatalog, canonicalModelId: string): WinterModelDescriptor[];

package/dist/families.js

@@ -0,0 +1,30 @@
+import {
+  SLOT_NAME_RE2,
+  FAMILY_ID_RE2,
+  CLAUDE_FAMILY_ID2,
+  OTHER_FAMILY_ID2,
+  CLAUDE_RESERVED_SLOT_NAMES2,
+  CURRENCY_RE2,
+  canonicalModelIdOf2,
+  familyIdOf2,
+  stampFamilyFields2,
+  resolveSlotName2,
+  familyOfModelKey2,
+  isSlotServableRow2,
+  rowsForCanonicalId2
+} from "./index-t40pzh81.js";
+export {
+  CLAUDE_FAMILY_ID2 as CLAUDE_FAMILY_ID,
+  CLAUDE_RESERVED_SLOT_NAMES2 as CLAUDE_RESERVED_SLOT_NAMES,
+  CURRENCY_RE2 as CURRENCY_RE,
+  FAMILY_ID_RE2 as FAMILY_ID_RE,
+  OTHER_FAMILY_ID2 as OTHER_FAMILY_ID,
+  SLOT_NAME_RE2 as SLOT_NAME_RE,
+  canonicalModelIdOf2 as canonicalModelIdOf,
+  familyIdOf2 as familyIdOf,
+  familyOfModelKey2 as familyOfModelKey,
+  isSlotServableRow2 as isSlotServableRow,
+  resolveSlotName2 as resolveSlotName,
+  rowsForCanonicalId2 as rowsForCanonicalId,
+  stampFamilyFields2 as stampFamilyFields
+};