{
  "schema": "shadowrun-japan-original-matchbox-guide-provenance/1",
  "date": "2026-10-25",
  "release": "shadowrun-japan-original-guide-1.1.0-2026-10-25",
  "scope": "The user requested an easier guide and Matchbox shortcut in the original Japanese browser player. This is an optional browser enhancement around the original emulated game.",
  "rom": {
    "file": "rom/shadowrun-japan.sfc",
    "bytes": 1310720,
    "sha256": "586551eadaff2693c0f21d9c47a697841989ae312d422fa4bf30823473a40fae",
    "modified": false
  },
  "enhancement": {
    "source": "matchbox-guide.js",
    "memory_bridge": "ram-bridge.js",
    "optional": true,
    "presentation": "A map sprite farther up-left outside the morgue and an original-style portrait dialogue scene. Offer, Yes/No replies, Use Matchbox, and the explicit return control are newly authored enhancement behavior.",
    "implementation": "The guide is a browser overlay projected using the current source-game camera. It is not an injected ROM NPC, source conversation script, or collision actor. The untouched cartridge continues to render and execute the rest of the game.",
    "guide_world_xyz": [
      458,
      622,
      64
    ],
    "street_entry_ids": [
      1,
      13,
      14,
      419
    ],
    "display_placement": "Matches the existing native recreation guide actor at world-screen175,129. At original entry1 camera300,182 the feet project to145,129.",
    "dialogue_language": "New English dialogue with recovered original font and portrait/frame art."
  },
  "original_japanese_matchbox": {
    "entity_id": 2240,
    "entity_id_hex": "08C0",
    "script_id": 294,
    "script_cpu_address": "9EE862",
    "script_rom_offset_hex": "0F6862",
    "state_wram_offset_hex": "3056",
    "flags_wram_offset_hex": "3057",
    "owner_wram_offset_hex": "3059",
    "jake_owner_hex": "08A4",
    "initial_state_hex": "00 00 00 A4 08",
    "initial_owner": "Jake already owns the Matchbox in the Japanese cartridge initial state.",
    "name_text_id": 713,
    "japanese_name": "マッチばこ",
    "examine_text_id": 129,
    "source_behavior": "Japanese script294 supplies Examine and Exit. It has no original hidden-room Use action or the Western examination/beep trigger. The new Use Matchbox control is therefore an enhancement, not a claim that the Japanese script contained that action.",
    "grant_behavior": "Accepting the new guide offer is idempotent. Only if the original item is not already owned by Jake does the bridge set its two-byte owner to08A4. The item flags and all other item/quest fields remain untouched."
  },
  "original_hidden_room": {
    "entry_id": 210,
    "entry_id_hex": "00D2",
    "room_table_rom_offset_hex": "069EE0",
    "room_data_rom_offset_hex": "0D0936",
    "entry_world_xyz": [
      394,
      488,
      64
    ],
    "travel": "Use Matchbox asks the original engine to load retained entry210. The real room, attendants, grants and source scripts run in the original game.",
    "return": {
      "entry_id": 1,
      "label": "Explicit return outside the morgue is added enhancement behavior. The original debug-room exit remains available.",
      "original_visible_exit": {
        "entity_id": 6482,
        "script_id": 235,
        "helper_script_id": 762,
        "destination_entry_id": 347
      }
    },
    "native5c": {
      "cpu_address": "80CD1D",
      "effects": "Writes requested entry to WRAM2FA2 and7FFF to1CDB. The source engine performs its normal fade, room allocation and player entry."
    },
    "excluded_helper": {
      "script_id": 285,
      "cpu_address": "9EE9E3",
      "called": false,
      "reason": "The retained helper writes player stats at3DB2,3DBA,3DBF,3DC1,3DBD,3DC2,3DBE before entering210. This enhancement uses only the bounded native5C-equivalent room queue."
    }
  },
  "memory_policy": {
    "address_basis": "All addresses below are offsets into the original 128KiB SNES WRAM; multi-byte values are little-endian.",
    "guards": [
      {
        "offset_hex": "0CC2",
        "type": "u16le",
        "expected_hex": "0056",
        "meaning": "Source player spawn slot on admitted street and debug room."
      },
      {
        "offset_hex": "150A + playerSlot",
        "type": "u16le",
        "expected_hex": "08A4",
        "meaning": "Active entity Jake; 140A is NOT the entity array."
      },
      {
        "offset_hex": "01C0",
        "type": "u16le",
        "expected_hex": "000F",
        "meaning": "Native brightness is fully visible, no forced blank."
      },
      {
        "offset_hex": "01CC",
        "type": "u16le",
        "expected_hex": "0000",
        "meaning": "Native brightness fade inactive."
      },
      {
        "offset_hex": "0208",
        "type": "u16le",
        "expected_hex": "FFFE",
        "meaning": "English/source text window stack empty."
      },
      {
        "offset_hex": "0254",
        "type": "u16le",
        "expected_hex": "0000",
        "meaning": "Native portrait conversation inactive."
      },
      {
        "offset_hex": "021C,021E,0220,0222",
        "type": "u16le each",
        "expected_hex": "FFFF",
        "meaning": "Japanese overlay text windows empty."
      },
      {
        "offset_hex": "1CDB",
        "type": "u16le",
        "expected_hex": "FFFF",
        "meaning": "No queued transition; alone this is not a loading guard."
      },
      {
        "offset_hex": "2FA2",
        "type": "u16le",
        "allowed_decimal": [
          1,
          13,
          14,
          419,
          210
        ],
        "meaning": "Street aliases and retained debug room only; action controls must use narrower room allowlist."
      }
    ],
    "stability": "The wrapper also waits for a stable admitted context after boot, state loads and transitions. Invalid, menu, dialogue, fade and room-loading contexts hide or disable the guide controls.",
    "allowed_writes": [
      {
        "offset_hex": "3059",
        "bytes": 2,
        "value_hex": "A4 08",
        "meaning": "Original Matchbox owner only. Idempotent if already Jake; default Japanese game already has Jake as owner."
      },
      {
        "offset_hex": "2FA2",
        "bytes": 2,
        "values_hex": {
          "debug": "D2 00",
          "return_street": "01 00"
        },
        "meaning": "Queue destination entry, same as native5C."
      },
      {
        "offset_hex": "1CDB",
        "bytes": 2,
        "value_hex": "FF 7F",
        "meaning": "Request native5C room loader, after destination write."
      }
    ],
    "invariants": "No ROM bytes, story-stage flags, money, karma, player stats, other inventory, actor coordinates or source save records are replaced. No prerecorded save state is loaded to grant the shortcut. Source debug-room interactions can subsequently make their own original changes when the player chooses them.",
    "loading_note": "1CDB returns toFFFF before the room finishes loading. Native brightness01C0=000F and fade-step01CC=0000 are required in addition to the empty window/conversation checks."
  },
  "artwork": [
    {
      "file": "../play/assets/street-guide.png",
      "bytes": 378,
      "sha256": "d4a7076604acdfabe1dff9a38d2032511b4efcff0351aa1bfa738dfa2cab495a",
      "role": "Original recovered map sprite",
      "note": "Existing native recreation asset, reused as the requested new guide. Its appearance does not turn it into an original cartridge actor."
    },
    {
      "file": "../play/assets/guide-dialogue.png",
      "bytes": 7429,
      "sha256": "ddd2ee73a174d336028fcd4514a9c8a3c284a221d00665f3a6c891587e032f69",
      "role": "Original portrait and frame artwork in an edited dialogue template",
      "note": "Existing 256x224 template retains the recovered Gray Decker and Jake portraits and dialogue frames. Source dialogue glyph regions were cleared for authored enhancement text."
    },
    {
      "file": "../play/data/english-font.json",
      "bytes": 13269,
      "sha256": "df7374a8f18cb5210a7622e82d11136027493aba025617fad7d7a3f451dbf944",
      "role": "Recovered original English glyph data",
      "note": "The retained English glyphs render newly authored English guide text."
    },
    {
      "file": "../play/engine/font.js",
      "bytes": 3643,
      "sha256": "2d8aa3aa13a571cc7f9438b7932a6390c482537a656758bfefd78e6df1cf96a8",
      "role": "JavaScript glyph renderer",
      "note": "Existing reconstruction renderer code; this is new software, not cartridge code."
    }
  ],
  "artwork_provenance": {
    "existing_notes": "../play/data/guide-dialogue-provenance.json",
    "source_capture": "street-room-13-dialog-0",
    "source_canvas_size": [
      256,
      224
    ],
    "npc_portrait": "Gray Decker, recovered original64x64 portrait",
    "player_portrait": "Jake, recovered original64x64 portrait",
    "template_edit": "Original portrait and frame pixels are retained; old dialogue text was cleared for the authored guide conversation."
  },
  "source_verification": {
    "method": "Local headless execution of the unchanged Japanese ROM through the existing Snes9x libretro research core. Only destination2FA2 and request1CDB were written for a street-to210-to1 round trip.",
    "round_trip": {
      "entity_state_records_compared": 701,
      "bytes_per_record": 5,
      "changed_entity_state_records": 0,
      "stats_range_hex": "3DB0..3DDF",
      "stats_unchanged": true,
      "story_stage_2FA4_unchanged": true,
      "party_2FA6_unchanged": true,
      "matchbox_owner_3059_unchanged": true
    },
    "fade_guard_proof": {
      "destination_entry": 210,
      "fade_started_frame": 1,
      "forced_blank_frame": 30,
      "new_player_coordinates_frame": 32,
      "full_brightness_frame": 87,
      "fade_inactive_frame": 89
    },
    "limits": "This record documents the source behavior and bounded memory policy. Website/browser verification is recorded separately with the release checks. Physical controller hardware is not claimed tested by this source proof."
  }
}