# Build-Fit Contract V1 Status: the versioned contract, hard extraction gates, deterministic five-piece verifier, four source-bound profiles, source expiry, a separate explainable evidence-coverage ranker, session-only aggregate context, and a read-only Builds surface are implemented and offline-tested. This document does not claim a new live or packaged UI acceptance. ## Purpose `build-fit-contract-v1` defines what must be known before an Artifact may enter a character/build evaluation. It remains separate from: - OCR/extraction confidence, which is a hard eligibility gate; - `roll-efficiency-v1`, which describes legal roll-tier quality without build context; - `build-fit-evidence-ranking-v1`, a separate product rule that ranks only source-bound profile evidence and is not a damage, optimizer, OCR-confidence, or Roll-Efficiency score. The foundation lives in: - `src/types/buildFit.ts` for versioned contracts and ranking payloads; - `src/lib/buildFitContractValidation.ts` for schema, safety-floor, and source- expiry validation; - `src/lib/buildFitEligibility.ts` for native-result mapping and deterministic eligibility evidence; - `src/lib/buildFitCombination.ts` for complete-build shape, aggregate-context, and conflict verification; - `src/lib/buildFitEvidenceRanking.ts` for bounded deterministic selection; - `src/lib/buildFitExplicitContext.ts` for session-only user-confirmed non-Artifact context; - `src/data/buildFitProfiles.ts` for curated assumptions, provenance, expiry, and direct source references; - `src/features/builds/*` for the read-only renderer surface. ## Contract Inputs Every character/build target provides: | Area | V1 requirement | | --- | --- | | Identity | Stable id, positive revision, character id/name, target id/label/role/description, and explicit unique assumptions | | Provenance | Game version, review timestamp, explicit expiry, and at least one versioned curated, user, or imported source | | Set plans | Explained preferred or alternative legal 2-piece, 4-piece, or 2+2 shapes | | Main stats | Explained priority 1-3 choices for Sands, Goblet, and Circlet; Flower and Plume stay fixed | | Substats | Unique canonical stats with explained relative weights in `(0, 1]` | | Aggregate targets | Optional full-build minimum/maximum targets; never inferred from one Artifact | | Evidence gates | Overall extraction confidence, required field confidences, and all identity/value fields | | Conflicts | Explicit `warn` or `block` behavior for equipment and cross-build assignment conflicts | V1 single-Artifact and combination assessments deliberately continue to emit `score: null` and `recommendationStatus: deferred`. The separate ranker can only work with a complete safe combination and a non-expired profile. ## Curated Profile Corpus `build-fit-profile-corpus-v2` has four deliberately narrow candidates. Every profile has a direct KQM reference, game-version label, review timestamp, and `validUntil` date. A stale profile fails closed before it can rank a build. | Profile | Scope | Sourced Set plan | Guide version | | --- | --- | --- | --- | | Furina Off-field Solo Hydro C0-C1 | Ousia off-field damage and Burst support; complete ER context required | 4pc Golden Troupe | KQM `Luna II` | | Neuvillette On-field Charged Attack | On-field Charged Attack damage, not driver-only | 4pc Marechaussee Hunter | KQM `Luna IV` | | Raiden Off-field Hyperbloom Trigger | Off-field Hyperbloom trigger only; no Burst/Aggravate/Quickbloom claim | 4pc Flower of Paradise Lost or 4pc Gilded Dreams | KQM `5.7` | | Nahida Off-field Deepwood Support | Off-field Skill application while Nahida is the intended Deepwood holder | 4pc Deepwood Memories | KQM `5.6` | The direct guide references are stored in `src/data/buildFitProfiles.ts`: - `https://keqingmains.com/q/furina-quickguide/` - `https://keqingmains.com/q/neuvillette-quickguide/` - `https://keqingmains.com/q/raiden-quickguide/` - `https://keqingmains.com/q/nahida-quickguide/` Tests validate every profile against vendored IK 6.7.0 character and Artifact- set keys. Each profile has a Golden complete-set fixture; Furina also has the context-pending fixture, and every additional profile has a Review adversarial fixture. No profile source is treated as a universal build rule outside its documented assumptions. ## Eligibility And Five-Piece Verification 1. A persisted native Artifact result maps to `build-fit-input-v1`; store-only rows are intentionally not used because they do not retain IK set keys and per-field confidence evidence. 2. Non-Artifact categories, Review, non-final extraction, missing fields, confidence below the contract floor, and free-text Set guesses block before profile evaluation. 3. `build-fit-combination-input-v1` verifies exactly five unique canonical slots, nested Artifact gates, complete 2pc/4pc/2+2 Set forms, sourced aggregate context, and conflicts in deterministic slot order. 4. Missing full-build context remains `pending`; a missed aggregate target is fit evidence, not an OCR repair opportunity. The verifier remains order-independent, source-bound, and score-free. ## Evidence Ranking And Explicit Context `build-fit-evidence-ranking-v1` is a separate, deterministic, read-only layer over complete eligible combinations from the newest complete native scanner run. It returns at most three non-overlapping profile suggestions. Its displayed `evidenceCoverage` is intentionally narrow and explainable: - a visible component for the sourced preferred or alternative Set plan; - the documented priority for the three variable main-stat slots; - presence/ordinal coverage of the profile's documented substats; - required aggregate targets only when they are met. It never uses Roll-Efficiency, artifact roll value, OCR confidence, a guessed character roster, team, weapon, rotation, or hidden damage constants as a rank component. OCR confidence remains a gate only. Conflicts stay visible as warnings and do not become a concealed damage penalty. Furina's 200%+ Solo-Hydro Energy Recharge target is the current aggregate context example. The user may enter and explicitly confirm the complete non-Artifact contribution for the current session. The value is not inferred from a scan, is not persisted, and is accepted only through the declared `local-build-context-v1` source. Without confirmation, Furina stays deferred. ## Builds Surface Boundary The Builds surface: - reads only the newest complete native result run, up to the 2,400-Artifact scan safety bound; - shows profile, Set path, five selected artifacts, rule coverage, sources, reasons, warnings, and blocked-context explanations; - exposes at most three non-overlapping candidates; - repeats that character ownership, team, weapon, and rotation are not proven by an Artifact scan; - never starts a scan, writes the Artifact store, edits a review, or sends in-game input. `src/lib/scoring.ts`, `data/presets.json`, and `createLocalAccountSnapshot` remain legacy/demo boundaries. Real local snapshots still do not run through the legacy scorer or emit legacy builds/recommendations. ## Next Acceptance Steps 1. The saved 20/50/100/2,211 validation gates passed for this checkpoint; preserve them for later Build-Fit changes and do not weaken scanner review gates. 2. The packaged renderer/UI acceptance passed. Keep it distinct from the optional elevated packaged-executable runtime/UAC claim. 3. Refresh every profile before its explicit expiry and add Golden plus Review/low-confidence adversarial coverage for every new profile. 4. The historical 136 Review crops were visually audited. For all new Review cases, require visual confirmation before changing parser or profile rules; do not relax gates from aggregate statistics. 5. Add later profiles only when their team/weapon/rotation assumptions can be represented explicitly without hidden constants. No suggestion may imply deletion, feeding, enhancement, or automatic in-game mutation.