# P1-003 evidence pack — provider redundancy and quality-aware routing

## 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`, and `OBS-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:

1. provider class and required capabilities match;
2. the locale and rights territory are explicitly allowed;
3. safety is approved, quota is available, and billing is not blocked;
4. cost and p95 latency remain within the request's hard limits; and
5. 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 / closed` for 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.
