@yanlinglabs/winter-provider-catalog 0.0.1

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@yanlinglabs/winter-provider-catalog",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yanlingLabs/winter-agent-sdk.git",
+    "directory": "packages/provider-catalog"
+  },
+  "homepage": "https://github.com/yanlingLabs/winter-agent-sdk",
+  "bugs": {
+    "url": "https://github.com/yanlingLabs/winter-agent-sdk/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./families": {
+      "types": "./dist/families.d.ts",
+      "default": "./dist/families.js"
+    }
+  },
+  "files": [
+    "dist",
+    "generated",
+    "overlay",
+    "schema",
+    "NOTICE",
+    "PROVENANCE.md",
+    "UPSTREAM.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "winter": {
+    "publish": {
+      "npm": true
+    }
+  },
+  "scripts": {}
+}

package/schema/catalog.schema.json

@@ -0,0 +1,238 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://winter.yanling.dev/schema/provider-catalog/v2.json",
+  "title": "WinterCatalog",
+  "description": "WS-13 §4's inert provider catalog. This schema is the CROSS-LANGUAGE contract (Lane X's generator, the Swift decoder, any external consumer); `packages/provider-catalog/src/validate.ts` is the in-repo gate and enforces four structural invariants JSON Schema cannot express on its own — global uniqueness of provider ids and model keys, per-provider uniqueness of `upstreamId ∪ aliases`, that every model's providerId names a provider present in the same document, and the secrets floor. Both must pass; neither substitutes for the other.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "catalogVersion", "upstream", "providers", "models", "families"],
+  "properties": {
+    "schemaVersion": { "const": 2, "description": "2 since WS-13c: every model row carries `modelFamily`/`canonicalModelId` and the document carries `families`." },
+    "catalogVersion": { "type": "string", "minLength": 1, "description": "\"0.0.0-seed\" marks the hand-authored seed; otherwise \"<upstream tag>+<extractorVersion>\"." },
+    "upstream": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tag", "tagObject", "commit", "extractorVersion", "overlayVersion"],
+      "description": "The upstream pin. Every field may be the EMPTY string: that is how the seed says no extraction produced it.",
+      "properties": {
+        "tag": { "type": "string" },
+        "tagObject": { "type": "string" },
+        "commit": { "type": "string" },
+        "extractorVersion": { "type": "string" },
+        "overlayVersion": { "type": "string" }
+      }
+    },
+    "providers": { "type": "array", "items": { "$ref": "#/$defs/WinterProviderDescriptor" } },
+    "models": { "type": "array", "items": { "$ref": "#/$defs/WinterModelDescriptor" } },
+    "families": { "type": "array", "items": { "$ref": "#/$defs/ModelFamilyDescriptor" }, "description": "WS-13c §1: the vendor lineups, generated from overlay/families.json and sorted by `id`. MAY be empty (a layer validated standalone has none); the `claude` reservation is enforced only when a family with that id is present." }
+  },
+  "$defs": {
+    "EvidenceSource": { "enum": ["official-doc", "live-discovery", "live-probe", "upstream-static", "user-override", "local-override", "winter-default"] },
+    "EvidenceConfidence": { "enum": ["verified", "declared", "inferred", "unknown"] },
+    "evidenceBase": {
+      "type": "object",
+      "required": ["value", "source", "confidence"],
+      "properties": {
+        "source": { "$ref": "#/$defs/EvidenceSource" },
+        "sourceRef": { "type": "string", "minLength": 1 },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "confidence": { "$ref": "#/$defs/EvidenceConfidence" }
+      }
+    },
+    "evidenceNumber": { "allOf": [{ "$ref": "#/$defs/evidenceBase" }], "properties": { "value": { "type": "integer", "exclusiveMinimum": 0 } } },
+    "evidenceBoolean": { "allOf": [{ "$ref": "#/$defs/evidenceBase" }], "properties": { "value": { "type": "boolean" } } },
+    "evidenceStringArray": { "allOf": [{ "$ref": "#/$defs/evidenceBase" }], "properties": { "value": { "type": "array", "items": { "type": "string", "minLength": 1 } } } },
+    "evidenceToolCalling": { "allOf": [{ "$ref": "#/$defs/evidenceBase" }], "properties": { "value": { "enum": ["native", "emulated", "none"] } } },
+    "evidenceReadableState": { "allOf": [{ "$ref": "#/$defs/evidenceBase" }], "properties": { "value": { "enum": ["none", "summary", "full-exposed"] } } },
+    "evidenceReplayScope": { "allOf": [{ "$ref": "#/$defs/evidenceBase" }], "properties": { "value": { "enum": ["current-tool-loop", "current-turn", "selected-turns", "all-turns"] } } },
+    "evidenceToolLoopRequirement": { "allOf": [{ "$ref": "#/$defs/evidenceBase" }], "properties": { "value": { "enum": ["hard-error", "silent-degradation", "not-required"] } } },
+    "evidenceString": { "allOf": [{ "$ref": "#/$defs/evidenceBase" }], "properties": { "value": { "type": "string", "minLength": 1 } } },
+    "evidenceSummaryRequest": {
+      "allOf": [{ "$ref": "#/$defs/evidenceBase" }],
+      "properties": {
+        "value": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["field", "values"],
+          "properties": { "field": { "type": "string", "minLength": 1 }, "values": { "type": "array", "items": { "type": "string" } } }
+        }
+      }
+    },
+    "evidencePricing": {
+      "allOf": [{ "$ref": "#/$defs/evidenceBase" }],
+      "properties": {
+        "value": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["inputPerMTokUsd", "outputPerMTokUsd"],
+          "properties": {
+            "inputPerMTokUsd": { "type": "number", "minimum": 0 },
+            "outputPerMTokUsd": { "type": "number", "minimum": 0 },
+            "cacheReadPerMTokUsd": { "type": "number", "minimum": 0 },
+            "cacheWritePerMTokUsd": { "type": "number", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "WinterProviderDescriptor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "displayName", "protocols", "authKinds", "defaultEndpoints", "modelDiscovery", "liveCatalogAuthority", "adapterId", "family", "upstream", "risk", "scope", "pricingBasis", "admission"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "displayName": { "type": "string", "minLength": 1 },
+        "protocols": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "enum": ["openai-responses", "openai-chat-completions", "anthropic-messages", "google-generate-content", "bedrock-converse", "azure-openai", "custom"] }
+        },
+        "authKinds": { "type": "array", "minItems": 1, "items": { "enum": ["api-key", "oauth-approved", "cloud-credential-chain", "local-none", "custom"] } },
+        "defaultEndpoints": {
+          "type": "object",
+          "description": "Generated endpoints are IMMUTABLE (R6-11). An EMPTY object is legal and meaningful: Azure/Bedrock/Vertex endpoints are region-, deployment- or project-templated and have no reviewable default. No userinfo, no query string.",
+          "additionalProperties": { "type": "string", "format": "uri", "pattern": "^https?://[^?#@]*$" }
+        },
+        "requiresUserEndpoint": {
+          "const": true,
+          "description": "P7a (WS-13b §2/§10): this provider's base URL is PER-TENANT, so the row ships none and a host/user supplies one. Only `true` is spellable — absence already means \"the endpoint is usable as shipped\". The in-repo validator additionally requires `endpointTemplate` and REFUSES any `defaultEndpoints.api` on such a row (a sentinel standing in for an endpoint is still an endpoint the runtime would call)."
+        },
+        "endpointTemplate": {
+          "type": "string",
+          "minLength": 1,
+          "description": "P7a (WS-13b §2/§10): the DOCUMENTED SHAPE of the per-tenant base URL, e.g. \"https://<resource>.services.ai.azure.com/openai/v1\". Documentation only — never sent, never parsed as a URL; it is what the runtime's `endpoint-required` refusal names. Meaningful only beside `requiresUserEndpoint: true`, which the in-repo validator enforces in both directions."
+        },
+        "modelDiscovery": { "enum": ["none", "openai-models", "provider-native", "local"] },
+        "liveCatalogAuthority": { "enum": ["authoritative", "partial", "unknown"] },
+        "adapterId": { "type": "string", "minLength": 1 },
+        "family": { "type": "string", "minLength": 1 },
+        "upstream": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["project", "commit", "sourcePaths"],
+          "properties": {
+            "project": { "enum": ["OmniRoute", "winter"] },
+            "commit": { "type": "string" },
+            "sourcePaths": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "risk": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["class", "reasons"],
+          "properties": { "class": { "enum": ["approved", "review-required", "blocked"] }, "reasons": { "type": "array", "items": { "type": "string" } } }
+        },
+        "scope": { "enum": ["llm", "stt", "tts", "embedding", "image", "video", "search"] },
+        "pricingBasis": {
+          "enum": ["token", "subscription", "free"],
+          "description": "WS-13b §1: how the vendor charges for the credential Winter uses. `subscription`/`free` rows never feed R6-H token cost."
+        },
+        "admission": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["basis", "citation", "tier"],
+          "description": "WS-13b §1 (D21): the documented third-party path this row ships through. `citation` is a vendor URL, `audit:<section>`, `spec:<section>` or `local`; the in-repo validator additionally REFUSES a citation naming the audit's `unknown` evidence class (R6b-3). `tier` is how good that evidence is (fix-wave R-FW-3): promotion is two-key — a live-gate pass AND a fetched vendor document — and no `approved` row or `supported` model may sit on `pinned-upstream`.",
+          "properties": {
+            "basis": { "enum": ["api-key", "oauth-documented", "keyless-documented", "local", "cloud-credential"] },
+            "citation": { "type": "string", "minLength": 1 },
+            "tier": { "enum": ["fetched-document", "pinned-upstream", "spec-ruling", "local", "audit"] }
+          }
+        },
+        "identityHeaders": {
+          "type": "object",
+          "description": "WS-13b §7/§8.4 (fix-wave R-FW-2): the SECOND identity field this vendor names, if it names one (AI Horde's `Client-Agent`). Winter-authored only: the in-repo validator restricts the NAMES to an allowlist and requires every value to START with the `<product>` placeholder — a hard-coded product token is refused, because it is truthful for exactly one brand. Three tokens are substituted by the adapter at request time: `<product>` (the running brand's package name), `<version>` (this build's) and `<contact>` (P7a fix wave — the running brand's contact URL, the half of a `<name>:<version>:<contact>` triple a vendor acts on). Sent beside the unconditional `User-Agent` and NOT gated on a generated endpoint — it is the running product's own identity, not the operator's.",
+          "propertyNames": { "enum": ["Client-Agent"] },
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "WinterModelDescriptor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "providerId", "upstreamId", "modelFamily", "canonicalModelId", "displayName", "aliases", "endpoints", "inputModalities", "outputModalities", "toolCalling", "nativeTools", "unsupportedParameters", "status"],
+      "properties": {
+        "key": { "type": "string", "minLength": 1, "description": "\"<providerId>/<upstreamId>\" (WS-13 §8.3). Split on the FIRST slash: an OpenRouter upstreamId is itself slash-bearing." },
+        "providerId": { "type": "string", "minLength": 1 },
+        "upstreamId": { "type": "string", "minLength": 1 },
+        "modelFamily": { "type": "string", "minLength": 1, "description": "WS-13c §1: the family id this model belongs to, or \"other\". DERIVED at build by `stampFamilyFields`; an overlay row MAY set it as an override." },
+        "canonicalModelId": { "type": "string", "minLength": 1, "description": "WS-13c §1: the vendor's model identity with the provider's spelling removed. DERIVED at build; an overlay row MAY set it as an override." },
+        "displayName": { "type": "string", "minLength": 1 },
+        "aliases": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "endpoints": { "type": "array", "minItems": 1, "items": { "enum": ["chat", "responses", "embeddings", "image", "audio", "video"] } },
+        "contextWindow": { "$ref": "#/$defs/evidenceNumber" },
+        "maxInputTokens": { "$ref": "#/$defs/evidenceNumber" },
+        "maxOutputTokens": { "$ref": "#/$defs/evidenceNumber" },
+        "inputModalities": { "$ref": "#/$defs/evidenceStringArray" },
+        "outputModalities": { "$ref": "#/$defs/evidenceStringArray" },
+        "toolCalling": { "$ref": "#/$defs/evidenceToolCalling" },
+        "nativeTools": { "$ref": "#/$defs/evidenceBoolean" },
+        "parallelTools": { "$ref": "#/$defs/evidenceBoolean" },
+        "structuredOutput": { "$ref": "#/$defs/evidenceBoolean" },
+        "promptCaching": { "$ref": "#/$defs/evidenceBoolean" },
+        "classifierEligible": { "$ref": "#/$defs/evidenceBoolean" },
+        "pricing": { "$ref": "#/$defs/evidencePricing" },
+        "reasoning": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["supported", "efforts", "continuation"],
+          "properties": {
+            "supported": { "$ref": "#/$defs/evidenceBoolean" },
+            "efforts": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "May be EMPTY: a model whose reasoning is budget-controlled (Gemini) or uncontrollable (DeepSeek reasoner) has no named-effort vocabulary." },
+            "defaultEffort": { "type": "string", "minLength": 1 },
+            "continuation": { "enum": ["none", "plaintext", "opaque-provider-state", "server-response-handle"] },
+            "readableState": { "$ref": "#/$defs/evidenceReadableState" },
+            "summaryRequest": { "$ref": "#/$defs/evidenceSummaryRequest" },
+            "replayScope": { "$ref": "#/$defs/evidenceReplayScope" },
+            "continuationDomain": { "$ref": "#/$defs/evidenceStringArray" },
+            "completionEvent": { "$ref": "#/$defs/evidenceString" },
+            "toolLoopRequirement": { "$ref": "#/$defs/evidenceToolLoopRequirement" }
+          }
+        },
+        "unsupportedParameters": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "status": { "enum": ["candidate", "experimental", "supported", "deprecated", "blocked"] }
+      }
+    },
+    "FamilySlot": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "WS-13c §2: one ranked option in a family's lineup. Position in the array is the option ORDER, not a strength claim — `description` and `reason` carry the meaning.",
+      "required": ["name", "canonicalModelId", "description", "reason", "basis", "citation", "status"],
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]{0,31}$", "description": "The facing enum token. `fable`/`opus`/`sonnet`/`haiku` are RESERVED to the `claude` family (D25)." },
+        "canonicalModelId": { "type": "string", "minLength": 1, "description": "Must resolve to at least one model row whose `status` is neither `blocked` nor `deprecated`." },
+        "provider": { "type": "string", "minLength": 1, "description": "Pins a serving provider id (WS-13c §4 step 4); it must survive the credential/enablement filter or the slot is unservable." },
+        "description": { "type": "string", "minLength": 1, "description": "No currency amounts — pricing lives on model rows with its own evidence." },
+        "reason": { "type": "string", "minLength": 1 },
+        "basis": { "enum": ["user-ruling", "vendor-doc", "winter-curated"] },
+        "citation": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["candidate", "supported"] }
+      }
+    },
+    "ModelFamilyDescriptor": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "WS-13c §1: a vendor lineup, independent of the provider that serves it. `matchers` are anchored RegExp SOURCES over `canonicalModelId`, first match wins, authored DISJOINT so the pipeline's sort-by-id can never change a row's stamp.",
+      "required": ["id", "displayName", "vendor", "vendorProviders", "matchers", "slots", "status", "citation"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$" },
+        "displayName": { "type": "string", "minLength": 1 },
+        "vendor": { "type": "string", "minLength": 1 },
+        "vendorProviders": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "ORDERED (WS-13c §4 step 3-i): a configured subscription row precedes a token row of the same vendor." },
+        "matchers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["pattern", "note"],
+            "properties": {
+              "pattern": { "type": "string", "minLength": 1 },
+              "note": { "type": "string" }
+            }
+          }
+        },
+        "slots": { "type": "array", "maxItems": 4, "items": { "$ref": "#/$defs/FamilySlot" }, "description": "0-4, unique names. A family with zero slots is legal — it is listed under \"more options\" only." },
+        "status": { "enum": ["candidate", "supported"] },
+        "citation": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}