# Gate 3 increment 5 service-orchestration report

Date: 2026-08-16
Exact base: `d7d2ad566af778b1d315616bbea8b8a3c4dd2191`
Exact core implementation and evidence head:
`2a7b3818c89a017c152f9f787c876891cc89e648`
Canonical commit: `aa182cc44883890c019c393f17602e2e2702e7d7`
Status: PASS canonical (PR #105, rebase merged)

## Results

| Gate | Result |
|---|---|
| Focused service contracts | 98 BESTIARY, model-client, and Watchtower tests; slowest affected test 0.060s and combined affected-test time 0.541s |
| Mandatory CPU lane | Python 3.12: 1,981 passed in 79.28s; 9 conditional tests deselected by policy; 0 failures, errors, skips, or unexpected warnings |
| Repository coverage | 76.76% statements / 63.49% branches before; 78.69% / 66.05% after |
| Mature CPU scope | 93.20% statements / 82.86% branches before; 93.26% / 83.05% after |
| Changed executable lines | 328/328 (100%) against the exact base |
| Touched production modules | 4/4 pass exact-base line and branch no-regression |
| BESTIARY adapter | `bestiary_sync.py`: 96.55% statements / 100% branches, from 0% / 0% |
| Catalog client | `models_client.py`: 92.86% statements / 92.00% branches, from 27.12% / 3.57% |
| Watchtower | `watchtower.py`: 96.99% statements / 92.22% branches, from 24.63% / 0% |
| Pure service seam | `service_contracts.py`: 100% statements / 95.65% branches |
| Selective mutation | 1,807/2,020 killed (89.46%); 208 survived; 5 timed out; 0 no-test, skipped, suspicious, interrupted, or segfault results |
| Changed service mutation | 189/189 killed; 0 survived or timed out; required-target guard passed |
| Repeatability | 595 tests passed in each of three file orders/hash seeds; 29.259s total; no flake candidates or consistent failures |
| Package | sdist and wheel built; required modules and console entry point present; isolated Python 3.12 wheel import/version contract passed |
| Policy and workflow | Locked dependency graph, Ruff F, actionlint 1.7.12, conditional policy, risk map, supply-chain policy, and 158 CI/policy contract tests passed |

The final mandatory lane added 98 passing tests relative to the canonical
increment-4 lane while completing 5.56 seconds faster (79.28s versus 84.84s).
The affected service tests consume 0.541s in aggregate, and no affected test
exceeds 0.060s. The repository branch-coverage Gate 3 exit of 65% is now met;
repository statements and mature-scope exits remain assigned to increments
6–7.

## Contracts added

1. An explicitly configured catalog path or URL is authoritative. Missing,
   oversized, non-UTF-8, malformed JSON, and invalid catalog envelopes fail
   closed instead of silently falling through to an unrelated local catalog.
2. Local and URL catalog reads are bounded at 8 MiB, URL reads use a finite
   timeout, and the stable catalog envelope and records are schema-checked.
3. Channel, vendor, and capability filters normalize case and whitespace;
   aliases remain stable; malformed list, vendor, identifier, date, and
   `open_weight` values are rejected rather than coerced.
4. Newest-model selection uses an injected UTC clock, validates its day window,
   falls back from `first_seen` to `released`, skips invalid dates, and sorts by
   the parsed effective date.
5. BESTIARY-derived presets preserve curated-ID authority and deterministic
   de-duplication, validate record fields, infer parameter tiers including MoE
   and unknown-size boundaries, and fail safe as one empty extension on a
   malformed catalog.
6. The Hugging Face adapter is injectable and deterministic. Per-organization
   failures are isolated, minimum-download filtering is enforced, malformed
   list/candidate responses are ignored or rejected at explicit boundaries,
   and no test performs a live service call.
7. License matching respects identifier boundaries, and instruction tuning is
   recognized by name tokens or exact tags rather than unsafe substrings.
8. Persisted Watchtower state loads transactionally: a malformed envelope,
   key/ID mismatch, field type, count, status, or metrics object cannot leave a
   partially accepted in-memory state. Failed temporary writes are cleaned up,
   and each in-process snapshot/write/replace sequence owns the shared
   temporary path until promotion completes.
9. Scheduler interval and status inputs are validated by pure contracts. Start,
   restart, stop, timeout, and start-failure transitions are explicit; a stuck
   thread remains owned and blocks a duplicate scheduler.
10. The scheduler runs immediately, stops through an injected event without
    sleep races, and safely defers confirmation when a callback requests stop
    from the scheduler's own thread, avoiding self-join and orphaning.

## Defects and mutants detected

The first focused campaign killed 166 of 194 service-contract mutants. The 28
survivors exposed weak boundaries around catalog field types, day/interval
validation, candidate defaults, state transitions, license matching, and exact
diagnostics. Survivor-driven tests and simplification of equivalent defaults
reduced the final pure seam to 189 meaningful mutants and killed every one.

Manual pre-delivery review then found two uncovered behaviors: string/integer
`open_weight` values could be truth-coerced, and a discovery callback could ask
the scheduler thread to join itself. Both now have reproducing tests and
fail-closed implementations. The fresh mutation prepass also rejected a stale
generated sandbox copy after these tests changed; rebuilding only the ignored
sandbox artifacts restored the exact 2,020-mutant campaign without touching
repository source.

The first exact-SHA audit found one further data-integrity gap: concurrent
scan/status saves could snapshot under the lock and then race on the shared
temporary file after releasing it. A controlled overlapping-writer test now
proves that snapshot, write, and replacement are serialized; related statistics
are captured under the same state lock.

The contracts additionally detect unbounded or ambiguous catalog resolution,
malformed records, case-sensitive filter drift, curated-preset replacement,
license/instruction substring false positives, non-deterministic organization
order, partial state acceptance, invalid lifecycle transitions, duplicate
background threads, and lost ownership after stop timeout.

## Verification and evidence

- Exact-head normalized JUnit, coverage, repeat, mutation, and trend evidence:
  `/tmp/obliteratus-item5-final-evidence-2a7b381/`
- Exact-head Python 3.12 raw coverage/JUnit evidence:
  `/tmp/obliteratus-item5-final-py312-2a7b381/`
- Exact-base canonical Python 3.12 evidence:
  `/tmp/obliteratus-postmerge-item4-py312-CH4T03/`
- Exact-head package artifacts and hashes:
  `/tmp/obliteratus-item5-package-2a7b381/`
- Installed-wheel verification environment:
  `/tmp/obliteratus-item5-wheel-env-2a7b381/`
- Canonical 8/8 hosted evidence:
  https://github.com/elder-plinius/OBLITERATUS/actions/runs/31933066525

The exact-head Ruff F gate, recovered pinned actionlint, `uv lock --check`,
conditional-policy validation, risk-map validation, changed-line gate,
touched-module gate, immutable quality policy, duration policy, repeat gate,
mutation score and required-target gates, package checks, and supply-chain
policy all pass. The canonical run completed all eight jobs successfully; its
1,805/2,020 mutation result differed from the PR/local 1,807/2,020 result only
because two simple mutants timed out on that runner and were killed on the
identical tree in both other campaigns. The original operator checkout was not
modified; work and evidence remained isolated in the dedicated item-5 worktree
and temporary paths.

## Scope and release decision

This increment implements Gate 3 bounded delivery item 5. It does not reopen
ordinary feature work: items 6–7, conditional-evidence reconciliation, and the
final canonical Gate 3 publication remain open. All catalog and Hugging Face
service behavior in this increment uses injected adapters, operator-provided
files, or loopback-style fakes. It makes no new live-network, remote,
accelerator, model-download, browser, or operator-UI support claim.
