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

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.
Non-Artifact categories, Review, non-final extraction, missing fields, confidence below the contract floor, and free-text Set guesses block before profile evaluation.
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.
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

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.
Perform a packaged renderer/UI acceptance before calling the new Builds surface live-accepted.
Refresh every profile before its explicit expiry and add Golden plus Review/low-confidence adversarial coverage for every new profile.
Visually label the remaining 136 Review crops before changing parser or profile rules; do not relax gates from aggregate statistics.
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.

7.8 KiB Raw Blame History