lib.provider-spec

@lssm-tech/lib.provider-spec

Website: https://contractspec.io

Typed provider-routing, runtime-target, execution-receipt, comparison, and patch-proposal contracts for the Builder control plane.

What It Provides

• Runtime-mode, provider-kind, task-type, risk, and comparison enums.
• Runtime target, handshake, trust-profile, and lease contracts.
• External execution provider, routing policy, context bundle, receipt, and patch proposal types.
• Validation helpers for routing policies, receipts, and runtime target records.
• Provider-neutral capability observations for usage, cost, latency, freshness, coverage, health, rate limits, trusted receipts, budgets, evidence, and replay.

Public Entry Points

• . resolves through ./src/index.ts
• ./types resolves through ./src/types.ts
• ./validation resolves through ./src/validation.ts
• ./provider-observation resolves the additive observation contract and pinned schema identity
• ./provider-observation-aggregation resolves deterministic aggregation and fail-closed budget evaluation
• ./provider-metering and ./provider-metering-runtime resolve additive reconciliation, health freshness, budget-reference, and tenant-query surfaces
• ./provider-shadow-selection and ./provider-shadow-selector resolve deterministic, explainable, no-dispatch provider shadow selection
• ./fixtures/provider-observation resolves neutral, no-network observation and budget fixtures
• ./gateway-model-catalog resolves the shared Vercel AI Gateway EU model allowlist (EU inference zone, zero retention, no training; Mistral excluded) used by CommunicationOS and OPA briefings, and ./gateway-model-resolution the deterministic request → user → workspace → environment → catalog precedence over it

Notes

• This package is a qualified pure platform spec (contractspec.architecture.role: platform-spec). Its runtime sources and their workspace suppliers perform no I/O, ambient clock or random reads, async effects or provider dispatch, so domain specs such as @lssm-tech/lib.builder-spec may depend on it directly.
• fingerprintProviderCapabilityDeclaration and validateProviderCapabilityDeclaration compute the SHA-256 digest synchronously with @lssm-tech/lib.crypto-utils/sha256. They keep their Promise return types, digests and rejection-on-malformed-input behavior.
• This package is a compatibility surface. Prefer additive evolution.
• Provider routing stays explicit policy, not hidden heuristics.
• Provider declarations use narrow Core serialization/features and the canonical @lssm-tech/lib.orchestration-spec/ai-improvement evidence declaration.

Provider type declarations are grouped internally by runtime target, routing, and execution receipt responsibility. The root and /types exports retain their existing names, literal unions, mutability, and structural contracts. Runtime leases and evidence references retain their existing authority boundaries.

Observation aggregation, input validation/grouping/cost summation and budget projection have separate cohesive private modules, per-observation accumulator updates separated from grouping and normalized output; each computational utility within 100 lines after canonical formatting, with the existing public facade. Aggregation remains deterministic and budget projection never grants external effect authority.

The additive ProviderWorkspaceInput, MobileParityInput, MobileReviewCard, and MobileParitySummary root exports are provider-neutral supplied-data contracts. They carry no workspace or approval authority. Builder retains its existing review-card and parity type names as aliases to the same canonical models.