genshin-assistant/docs/BUILD_FIT_CONTRACT_V1.md

# 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. Perform a packaged renderer/UI acceptance before calling the new Builds
   surface live-accepted.
3. Refresh every profile before its explicit expiry and add Golden plus
   Review/low-confidence adversarial coverage for every new profile.
4. Visually label the remaining 136 Review crops 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.