Work-package charter#
- Task ID:
P1-003 - Owner: shared provider-routing and contracts maintainers; implementation owner: Elikem Agudogo
- Accountable product: shared V1–V9 provider control plane
- Priority: P1
- Target milestone: 2026-07-15 SOTA gap-closure program
- Risk tier: Critical provider outage, unsafe routing, rights violation, silent degradation, and false-redundancy risk
- Dependencies: calibrated and freshness-bounded provider outcome telemetry, immutable provider/model/endpoint and failure-domain identity, capability, locale, rights, safety, quota, billing, cost, latency, and regional-health inputs, plus consequential product dispatchers that consume and surface the decision envelope
- Affected schemas and content slots: provider candidate, route request, decision, score, degraded-label, drill, portfolio, and certification contracts for ten critical provider classes. The contract can govern every V1–V9 content slot that invokes one of those classes, but this work package changed no product dispatcher, prompt, artifact, rendered UI, media byte, or released slot.
- Linked task IDs:
P1-003,P1-004,EVAL-004, andOBS-001 - Scope: closed-world critical-class definition, strict provider and request schemas, multidimensional route eligibility and scoring, exact route identity, mandatory degraded labeling, five-scenario failover drills, typed certification gate, root exports, and CI verification
- Rollout strategy: assemble candidates only from fresh provider telemetry and calibrated outcome evidence, certify the complete active inventory, then require consequential provider dispatchers to consume the decision envelope and surface its customer label.
- Rollback strategy: revert schema, router, certification, tests, export, verification script, workflow, evidence, and ledger closure together. Never fall back to static preference or suppress a degraded/blocked label.
- Evidence-pack location: this file
Implemented routing and certification boundary#
The shared contract defines ten critical provider classes: text generation, embedding, image generation, audio generation, video generation, speech synthesis, speech recognition, moderation, payment, and notification delivery. Certification requires an exact request for every class and at least two independent provider identities and failure domains per class.
Provider eligibility fails closed unless all of these conditions hold:
- provider class and required capabilities match;
- the locale and rights territory are explicitly allowed;
- safety is approved, quota is available, and billing is not blocked;
- cost and p95 latency remain within the request's hard limits; and
- quality meets the calibrated score, sample-size, and evidence-freshness floors.
Eligible providers are ranked with normalized, caller-visible weights for calibrated quality, capability, cost, latency, locale, rights, safety, and preferred-region availability. Stable provider, model, and endpoint identities break exact score ties, so input order cannot change a decision.
Every approved decision preserves endpoint, provider, and model identity for the
selected route and failover chain. Incident and regional-fallback decisions must
use degraded mode and a non-empty Degraded provider route: … customer-facing
label. A blocked route receives Provider route unavailable; there is no
unlabeled fallback.
Drill matrix and adversarial verification#
The canonical certification fixture contains two independent candidates for each of the ten critical classes. For each class, it selects a normal baseline then executes:
- primary outage;
- calibrated quality regression below the quality floor;
- quota exhaustion;
- billing block; and
- preferred-region outage.
All 50/50 drills switch to a different provider identity and retain exact replacement endpoint/model identity plus degraded labeling. The complete focused suite passes 21/21 adversarial cases.
Negative cases prove fail-closed behavior for missing or duplicated class requests, duplicated endpoints, same-provider endpoint-only redundancy, shared failure domains, absent regional redundancy, missing capabilities, stale or undersampled quality evidence, low calibrated quality, excessive cost/latency, locale and rights mismatch, unsafe providers, exhausted quota, blocked billing, unknown schema fields, non-normalized weights, nondeterministic input order, and typed certification failure.
Focused ESLint passes with zero warnings, the contracts production TypeScript
project passes with zero errors, and the targeted @oshun/contracts build
passes with conservative Nx parallelism. Before the build, the 15 GiB host had
11 GiB available, 29 GiB of swap free, 15 GiB of disk free, and no competing
build/test process. Source pre-commit linting, formatting, convention ratchets,
asset locking, and V5 document validation also passed.
Current admitted verification#
The current refresh ran against repository commit
9b98a0e099366daf610aba042ad779c899376b16 with lockfile SHA-256
08b055786e9b8a6104d5313601d7eef3205dedcf395066fd9a8264c9859d690f on host
app-dev-server, Ubuntu 24.04.4 LTS, Linux 6.8.0-134-generic x86_64. The
relevant toolchain was Node.js v24.15.0, pnpm 10.25.0, TypeScript 6.0.3,
ESLint 10.4.0, Vitest 4.1.7, and Nx 22.7.4.
No live provider/model, credential, customer traffic, production telemetry, outage, quota/billing receipt, rights grant, operator decision, or deployed dispatcher was used. All 20 provider candidates and quality observations are closed-world fixtures and are never represented as production certification.
| UTC interval | Exit | Exact command and result |
|---|---|---|
| 2026-07-29T11:58:39.746Z–2026-07-29T11:59:19.514Z | 0 | pnpm verify:contracts:provider-routing — zero-warning ESLint over implementation, tests, and exports; the focused suite passed 21/21; libs/contracts/tsconfig.lib.json production typechecking passed |
| 2026-07-29T11:59:37.856Z–2026-07-29T12:00:36.418Z | 0 | NX_DAEMON=false NX_TUI=false pnpm nx run @oshun/contracts:build --parallel=1 --skip-nx-cache — uncached targeted contracts TypeScript build passed. At the 30-second poll, 10 GiB memory remained available and no stop threshold was approached. |
The admitted suite covers the applicable boundaries:
- Unit/schema/contract: every critical class, route input, weighting, eligibility dimension, score, exact identity, label, drill result, and certification condition is value-asserted.
- Integration: canonical common/root exports, the root verification command, dedicated CI workflow step, production typecheck, and uncached package build all consume the same contract.
- Adversarial/negative: 21 cases include missing/duplicated inventory, endpoint-only pseudo-redundancy, shared failure domains, stale/undersampled or low quality, missing capabilities, excessive cost/latency, locale/rights/ safety mismatch, quota/billing blocks, region loss, unknown fields, non-normalized weights, nondeterministic order, and typed certification failure.
- Repository E2E/drills: all 50 class/scenario drills route to a distinct provider/failure domain while preserving exact route identity and degraded labeling. They are hermetic drills, not deployed traffic failover.
UI/accessibility automation, screenshots/media probes, mobile/Unreal automation, production performance/load testing, and a deployed E2E are inapplicable to this contract-only implementation and evidence refresh. No rendered customer label surface, media artifact, mobile flow, Unreal asset, provider network, or production dispatcher changed.
Claim boundary#
This closes the executable repository contract and deterministic drill matrix. It does not assert that all deployed V1–V9 provider integrations have been inventoried, that production telemetry has populated the candidate schema, that live customer traffic has failed over, or that any external provider issued an outage/quota/billing/regional receipt. The canonical providers and quality observations are test fixtures, not measured provider rankings or production certification evidence. Product dispatchers must still adopt the decision envelope before a deployed portfolio may claim operational certification.
Release, authority, blocker, and generated-status disposition#
- The repository verdict is
repository-complete / closedfor P1-003. A deployed portfolio remains uncertified until its complete active inventory, current telemetry, real dispatcher adoption, customer label propagation, and operational drills produce exact evidence. - No P1-003 repository schema or test policy requires a signed human decision to publish the contract. Production provider onboarding, rights/safety approval, degraded-mode operations, and certification remain subject to their owning human/operator authorities. No reviewer identity, signature, provider approval, or operational receipt is fabricated here.
- Remaining external dependencies are deployed-provider inventory, calibrated outcome telemetry, live health/quota/billing/rights signals, dispatcher adoption, user-visible labeling, and provider/traffic failover receipts. Fixtures cannot discharge them.
- No generated capability/status artifact advertises a certified deployed provider portfolio. The completed-work-package admission verifier derives only this checked task's evidence-pack presence and identity; no generated production-green claim was hand-edited for this refresh.
Publication identity#
- Implementation source commit:
266a0ae959b713e87d9a833d41c4b80d8d2c5f4c - Published at:
2026-07-24T13:40:00Z - Closure evidence commit:
1c1c5a9b0937032bc798217975cd42bf63c0e8b0 - Current refresh source commit:
9b98a0e099366daf610aba042ad779c899376b16 - Current refresh evidence commit: this evidence-only publication commit; the immutable identity is the Git commit containing this file.
| Artifact | SHA-256 |
|---|---|
libs/contracts/src/common/provider-routing-certification.ts |
e35a215a5386dc066bf63097b2ad838684f8ab647097d78723d543718afc1109 |
libs/contracts/src/common/provider-routing-certification.spec.ts |
1f2bc49b8e6a612b0a83dd5b3dd402de4b94dce57784dbafac1c47de85dd7694 |
libs/contracts/src/common/index.ts |
a557ed7f6dc5614b63cf60fc33ad6109c5831757a845125d016df710dd5e0d25 |
package.json |
c6f342a2399a4708ca7dcbe9d0f484f5da8915dc67c6a01cd10bc62884ef5c10 |
.github/workflows/content-slot-contract.yml |
37e02a066006145bd238e8a89cd250d3d1149da372f81a38dfefc8469d550b19 |
The implementation and adversarial-test hashes still match current source. Shared export, root-script, and workflow hashes changed as other contract gates were added; the current verifier and uncached build validate the integrated surfaces. Provider, model, endpoint, quality evidence, rights, safety, region, and route identities are runtime inputs rather than hard-coded production versions. No prompt, canon, policy, rubric, model/provider, source, or released artifact version changed in this evidence refresh.