genshin-assistant/docs/ARTIFACT_EVALUATION_OFFLINE_VALIDATION_2026-07-10.md

# Artifact Evaluation And Offline Validation - 2026-07-10

Historical pre-live snapshot. The deferred live work described here was
completed later on 2026-07-10; see
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).

This report records the implementation of the five post-ingestion phases. No
live Genshin smoke test was run during this work. Existing native scan results
were used as the only real Artifact input.

## Implemented Phases

### 1. Deterministic Artifact evaluation

- `src/lib/artifactEvaluation.ts` implements `roll-efficiency-v1`.
- The score measures legal substat roll-tier efficiency from `0-100`; it does
  not pretend to be universal character or build value.
- Main stat validity, extraction confidence, roll legality, and build fit stay
  separate.
- Clean results become `evaluated`; uncertain extraction remains `review`;
  inconsistent or incomplete clean data becomes `unknown` instead of receiving
  a fabricated score.
- Locked and equipped state do not change Artifact quality.

### 2. Inventory and detail integration

- Native `scan-results.json` entries now carry a versioned value evaluation,
  score, reason codes, legal roll counts, and per-substat efficiency.
- Legacy saved results are evaluated on load without requiring a rescan.
- The scan result rail shows compact roll-efficiency values.
- Inventory adds evaluated/open filters and roll-value sorting.
- Artifact detail shows score reasons, roll breakdown, and the explicit
  `Build-Fit offen` boundary.
- Review results never receive a normal quality score.

### 3. Offline packaged-app verification

- Electron was upgraded from 33 to `43.1.0` because the old runtime was listed
  by the production dependency audit.
- Deprecated `NativeImage.getBitmap()` calls were migrated to `toBitmap()`.
- `electron-builder`, `@electron/asar`, and repeatable package scripts were
  added.
- `npm run package:offline-check` builds the C# helper, renderer, Electron main
  process, and an unpacked Windows app without launching it.
- `scripts/verify-packaged-app.mjs` verifies the executable, ASAR entries,
  relative renderer assets, current runtime signature, preload, helper, IK
  lists, and matching IK version.
- Packaged helper and IK lookup now use only `process.resourcesPath` by default;
  repository paths remain development-only and cannot mask missing packaged
  resources.
- The unpacked app passed `27/27` project/package checks. Runtime launch and
  Genshin interaction remain deliberately deferred to the next live session.

### 4. Offline repeatability replay

- `npm run scan:native:replay -- --run-dir=<saved-run> --repeats=5` evaluates a
  saved `scan-results.json` repeatedly and compares deterministic SHA-256
  payload hashes.
- It writes `outputs/native-replay/<run>/native-replay-report.json` and fails if
  a clean parsed Artifact cannot be evaluated.
- The replay never focuses, captures, clicks, scrolls, or starts Genshin.

| Saved run | Repeats | Results | Evaluated | Review | Unknown | Projection | Deterministic |
| --- | ---: | ---: | ---: | ---: | ---: | --- | --- |
| `20260709-223006` | 5 | 20 | 20 | 0 | 0 | 20 complete | yes |
| `20260709-223041` | 5 | 50 | 49 | 1 historical review | 0 | 49 complete | yes |
| `20260709-223441` | 5 | 100 | 100 | 0 | 0 | 9 available, 91 complete | yes |

The 100-result run produced a score range of `76.1-92.5` with average `84.3`.
This is roll-tier efficiency, not build fit.

### 5. Upgrade projection

- Under-leveled, unambiguously identified 5-star Artifacts with four known legal
  substats receive deterministic worst/middle/best roll-efficiency bounds up to
  +20.
- The calculation uses remaining +4 steps and legal rarity-specific roll tiers.
- Three-substat, 4-star, ambiguous-rarity, review, incomplete, or illegal data
  disables projection.
- +20 Artifacts are marked complete and do not show invented future rolls.
- Every visible projection states that target substat and roll tier are random
  and that the result is not guaranteed.

## Static Evidence

- `npm run lint`: passed
- `npm test`: passed, `262/262` tests in `40/40` files
- `npm run build`: passed
- `npm run eval`: `26/26` exact cases, `77/77` fields
- `npm run scan:assessment:test`: passed
- `npm run package:verify`: `27/27` checks passed
- `npm audit`: `0` vulnerabilities
- `npm audit --omit=dev`: `0` vulnerabilities
- `git diff --check`: passed; only the known line-ending warnings may be shown

## Additional Non-Live Runtime Evidence

The current source build was started once through the normal non-elevated dev
runtime without calling capture, preflight, probe, click, scroll, or scan
endpoints. It proved the following boundaries without sending Genshin input:

- `/health` reported the current runtime signature, one main window, and all
  four registered hotkeys.
- `/scanner/status` found `GenshinImpact`, reported `isElevated: false`, and
  reached the C# helper while the native scanner remained `idle`.
- IK data `6.7.0` loaded as valid with 61 Artifact sets and 289 pieces;
  weapons, characters, and materials remained `catalog_only`.
- Four OCR workers warmed successfully in `212 ms`.
- The saved 100-result run loaded through the runtime and legacy `deferred`
  values were enriched to `evaluated` without rewriting the source run.
- A valid native PNG crop loaded successfully. An outside path, a JSON file,
  and a traversal path were all blocked with HTTP `409`.
- The runtime was then shut down through `/dev/shutdown`; no stale Electron
  process or port listener remained.

`npm run scan:native:validate:saved` now validates the newest complete
20/50/100 evidence set in one read-only command. It checks run contracts, PNG
containment, non-persistence, review-log provenance, five-repeat determinism,
scores, and projection boundaries. The current evidence set passed with zero
issues.

`npm run acceptance:offline` is the durable umbrella gate for work that does
not require Genshin input. It runs lint, all unit tests, OCR eval, assessment
self-test, saved native evidence validation, a fresh helper/app package build,
27 package checks, full and production dependency audits, and
`git diff --check`. The current run passed every step and writes its machine-
readable report under `outputs/offline-acceptance/`.

## Deliberately Not Claimed Yet

- No packaged executable was launched.
- No live Smart Capture or native scan was started.
- No later-session 20/50/100 live repeatability claim was added.
- No Inventory Kamera parity or 3-artifacts/second end-to-end claim was added.
- Build-fit scoring and account recommendations remain separate later work.

The required live and visual checks are listed in
[TOMORROW_LIVE_TEST_PLAN_2026-07-10.md](TOMORROW_LIVE_TEST_PLAN_2026-07-10.md).