# Analyzer Architecture and Stage Contracts

**PFES revision:** 0.13.0

This document is the human-readable companion to `ANALYZER_STAGE_CONTRACTS.json`.

## stage1 — Extraction and provenance staging

**Canonical implementation path:** `scripts/toolchain/hlds_stage1_extractor.py`

**Inputs:** firmwarehq_LG tree; direct .bin/.dld payloads; archives; vendor updater executables; optional new-style PE probes; Sydex/CopyQM pre-ingest outputs.

**Outputs:** staging_candidates/; stage1_payload_index.json; stage1_inventory.csv; stage1_sydex_preingest_index.json when used; stage1_sydex_preingest_inventory.csv when used; logs/.

**Responsibilities**
- discover and extract without modifying source corpus
- hash every candidate
- retain all source paths and extraction methods
- stage direct, archive, executable, DLD-carve, Disk eXpress, PE-resource and guarded new-style candidates
- accept Sydex-style pre-ingest as a container layer

**Must not**
- decrypt firmware
- disassemble
- promote diagnostic SXD streams as firmware
- discard provenance instances because bytes match

**Promotion gate:** A candidate is only staged. It is not yet firmware, plaintext, executable, or safe.

## stage2 — Conservative normalization

**Canonical implementation path:** `scripts/toolchain/hlds_stage2_normalizer.py`

**Inputs:** stage1_payload_index.json; staged candidate bytes; PRM metadata when available.

**Outputs:** normalized_payloads/; stage2_payload_manifest.json; stage2_inventory.csv.

**Responsibilities**
- validate DLD structure
- split DLD firmware and optional stub components
- parse PRM entries
- match PRM entries by package, filename and size
- copy raw BINs without speculative transformation
- assign explicit role and container provenance

**Must not**
- decrypt
- opcode-density analysis
- checksum verification
- profile generation

**Promotion gate:** Role and container identity must be explicit; missing stub is not negative evidence.

## stage3 — Conservative routing

**Canonical implementation path:** `scripts/toolchain/hlds_stage3_router.py`

**Inputs:** stage2_payload_manifest.json; normalized payloads.

**Outputs:** stage3_routing_manifest.json; stage3_routing_inventory.csv; stage4_decrypt_candidates.json; Stage5 direct-analysis and review routes.

**Responsibilities**
- route by role, container and byte evidence
- keep stubs out of decryption
- distinguish donor, validation-reference and recipient-candidate scope
- optionally send guarded raw/new-style probes to Stage4
- route canonical HITMEM ROMs as direct plaintext in the v5 lineage

**Must not**
- decrypt
- disassemble
- treat heuristic byte profile as proof
- promote GDR-3120L as a recipient target

**Promotion gate:** Uncertain raw/new-style data remains review-only unless Stage4 returns strong plaintext evidence.

## stage4 — Representation transform and guarded plaintext recovery

**Canonical implementation path:** `scripts/toolchain/hlds_stage4_decryptor.py`

**Inputs:** stage4_decrypt_candidates.json; stage3_routing_manifest.json; normalized payloads.

**Outputs:** decrypted_payloads/; stage4_decryption_manifest.json; stage4_decryption_inventory.csv; stage5_analysis_inputs.json.

**Responsibilities**
- apply old-DLD GCC/GDR transposition-plus-XOR transforms
- pass already-plaintext candidates through when evidence is strong
- reject weak raw KPA results to review
- pass canonical HITMEM ROMs through unchanged in the v5 lineage
- preserve transform family and confidence

**Must not**
- decrypt stubs
- verify firmware checksum
- promote weak output because it looks plausible
- erase original representation

**Promotion gate:** Accepted output must meet plaintext sanity criteria or be an explicitly trusted direct-plaintext source.

## stage5a — MN103S disassembly and topology handoff

**Canonical implementation path:** `scripts/toolchain/hlds_stage5a_disassembler.py`

**Inputs:** stage5_analysis_inputs.json; plaintext firmware and stub binaries.

**Outputs:** disassembly/*.asm; stage5_disassembly_manifest.json; stage5_disassembly_inventory.csv; stage5b_analyzer_inputs.json.

**Responsibilities**
- invoke MN103S objdump
- record command, base, role and provenance
- use fixed stub base unless overridden
- use a pointer-lane heuristic for firmware VMA unless forced
- optionally include review inputs

**Must not**
- treat VMA heuristic as hardware proof
- perform semantic command analysis
- require Ghidra

**Promotion gate:** Disassembly success means bytes were decoded at a declared base, not that functions or hardware semantics are correct.

## stage5b — Evidence collection and candidate synthesis

**Canonical implementation path:** `scripts/toolchain/hlds_stage5b_analyzer.py`

**Inputs:** stage5b_analyzer_inputs.json; plaintext binaries; objdump disassemblies.

**Outputs:** stage5b_analysis_manifest.json; stage5b_findings_inventory.csv; stage5b_smc_gpio_candidates.json; stage5b_findings_store/ in current lineage; stage6_profile_candidates_compact.json; stage6_profile_candidates.json when legacy output is enabled; logs/.

**Responsibilities**
- collect strings, command surfaces, tables, pointers, caves, vectors, flash and hardware evidence
- retain negative and expected-absence evidence
- emit per-payload and category-organized findings
- support scoped/smoke runs before full reruns
- separate direct opcode, table-dispatch, semantic-handler and cross-family evidence

**Must not**
- patch firmware
- verify checksums
- declare live hardware safety
- equate missing direct compare with missing handler
- penalize recipient PC firmware for absent donor-only auth logic

**Promotion gate:** Findings remain candidates until corroborated by stronger static evidence, emulation, command-level behavior, or hardware.

## post5b — Report synthesis, support candidates and rankings

**Canonical implementation path:** `scripts/toolchain/make_hlds_gc_wii_support_candidates.py and ranking helpers`

**Inputs:** Stage5B manifest, findings inventory and finding store; hardware inventory; provenance records.

**Outputs:** support-candidate reports; strict purchase-validation candidates; record watchlist; near-purchase rollups; recipient rankings; result ZIPs.

**Responsibilities**
- convert evidence to explicitly gated recommendations
- keep model and model-version rollups separate
- preserve provenance-distinct rows
- distinguish strict purchase candidates from watchlists
- archive generated result sets

**Must not**
- convert a score into hardware validation
- deduplicate stock and patched variants
- label GDR-8050L stock firmware as ordinary GC/Wii support

**Promotion gate:** Recommendations are planning outputs, not proof of support or safe purchase.
