← WI-012 Output validation core — trust pipeline (stages 0–9, issue/receipt model, rule registry, deterministic repair, branded TrustedScanResult) ★ Live Board · Overview WI-014 Source ingestion + promotion CORE contract (one-door flow, promoteInventoryCandidate, idempotency, layered dedup, provenance, plugin-event audit, permission matrix) →

WI-013 · Platform & Contracts · deterministic-ranking

Candidate ranking engine — deterministic features, fixed-point scoring, priority bands, tie-break, explainability, canonical hash

queued P1 medium risk   Owner: Paul   0% · 0/5 tasks complete

Gates: P4 Requirements: REQ-CONTRACT-004 Updated: 2026-06-22

At a glance

CodeWI-013
PhasePlatform & Contracts
Order13 of 93
Story points8
Primary surfaceRanking engine library (pure: TrustedScanResult [branded canonical P1 ScanResult] + context -> ordered result)
Retires—
Depends onFreeze scan I/O contract schemas + versioning, Output validation core — trust pipeline (stages 0–9, issue/receipt model, rule registry, deterministic repair, branded TrustedScanResult)
BlocksRanking replay & calibration tooling (historical replay, policy comparison, offline outcome metrics)
Evidence
docs/CC-Analysis/trovesnap-vision-scanning-spec.md (20)

Goals

Deterministic candidate ranking computed by TroveSnap from the model's component scores (never the model's own ordering), with documented per-profile weights (§20).

Spec document

P4-candidate-ranking → · source ↗

Implementation — what to build

Spec (docs/specs/P4)

  • Model returns validated evidence; TroveSnap derives features. Pure function — no time/db/randomness/LLM/provider; demand external; per-intent policies.
  • Consumes the P3 TrustedScanResult = the branded CANONICAL P1 ScanResult (nested: result.payload.candidates[].{id,confidence int 0-100,...}, region for visibility, watchlist_matches[].confidence int 0-100, model_priority_hint enum). Features derive from these validated fields; the ranker reads the canonical shape directly (no flat fork).

Build (engine)

  • Eligibility → feature extraction (watchlist_relevance, demand_signal, appraisal_potential, evidence_quality, visibility) → missing-feature policy → priority bands → fixed-point weighted score (+caps) → stable tie-break → explanation generator → canonical serializer + ranking_hash. Policy/feature/weight/extractor/tie-break registries; personal-hunt + estate-organizer policies.

Test (keyless)

  • Golden score/order (both intents); input-order invariance; idempotence; monotonicity; bounds (property-based); tie-break; missing-feature; feature-extraction; priority-band; config validation; partial-result; cross-runtime hash stability.

Freeze (§38)

  • P1 model_priority_hint rename note; F demand-snapshot contract; P6 ranking/profile/snapshot storage.

Checklist

  • ○ Consume the P3 TrustedScanResult = branded canonical P1 ScanResult (result.payload.candidates[].{id,confidence int 0-100}, region, watchlist_matches[].confidence) — depends on WI-012 (validation-pipeline).
  • ○ Have the model return component scores (watchlist_match, demand_signal, value_potential, confidence, visibility) — not a final rank.
  • ○ Implement the ranker with profile weights (personal_hunt vs estate_organizer) (§20).
  • ○ Guarantee reproducibility: same evidence → same order (snapshot test).
  • ○ Document the weights and how to add a new ranking profile.

Gates & testing

  • ○ P4 Deterministic candidate ranking: the model returns evidence/component scores; TroveSnap computes the final ranking.
    CODE TEST

Requirements

  • REQ-CONTRACT-004 accepted Candidate ranking must be deterministic, computed by TroveSnap from model evidence (not by the model).
    Done when: The model returns component scores; TroveSnap computes the final ranking with documented per-profile weights (personal_hunt vs estate_organizer).
    Spec: docs/CC-Analysis/trovesnap-vision-scanning-spec.md (20)

Verify (done when)

Pure CandidateRankingEngine: only P3 trusted results enter (the branded canonical P1 ScanResult minted by WI-012 — P3 does not reshape); features deterministically derived from validated evidence + supplied context (model supplies no authoritative score); fixed-point integer scoring + caps; deterministic priority bands; stable total-order tie-break ending in candidate ID; per-intent policies (personal_hunt + estate_organizer); explanation codes + canonical ranking hash; golden/property/config tests pass (bounds, input-order invariance, idempotence, monotonicity). Per spec §35/§36 (engine rows). §38 reconciliations before freeze.

Cost triggers

No paid API / infra spend triggered by this item.

Status & editing

queued   Sprint: P&C Wave 2: Core Contracts

Edit status / sprint on the ★ Live Board → — changes are logged live with who / when / why.

Human-in-the-loop

No human tasks linked.

Findings

None recorded yet.

Concerns

None recorded yet.

Risks

None recorded yet.

Tech debt

None recorded yet.

Tools used

No tool calls recorded.

Files & artifacts

No files / artifacts recorded.

Update log

No log entries yet.