Nexus SAL MAP Internals

Nexus SAL/MAP Bounded Route

DONE

The retail Japanese corpus at FIRESTAFF_NEXUS_DATA_DIR contains sixteen SNDLEV00 through SNDLEV15 SAL/MAP pairs. Per DMWeb's DecodeSNDLEVxxMAP, each MAP is a sequence of eight-byte records beginning at byte zero and ending with an ffff terminator; the verified files are 66–90 bytes, so there is no 24-byte leading file header. The implemented record route retains only the observed fields: raw selector byte, raw attribute byte, big-endian SAL offset, and big-endian SAL size. It accepts a selector only when it occurs exactly once and its complete SAL window is in bounds. The focused corpus test covers all sixteen pairs.

The SAL side now also decodes the DMWeb DataID 0 tone-bank directory from the real SAL stream: its big-endian entry-offset table, four variable entries, the later 4 + 32*n entries, PCM width bit, source-control bit, and bounded sample payload metadata. This is still not an audio route: the MAP selector and attribute have no asserted Saturn event meaning, and no playback is requested from this result.

The directory cursor is the post-skip cursor after the first two mapped SAL regions. For the level-0 retail witness this is 0x540 + 0xAC0 + 0x10040 = 0x11040; the first directory word there is 0x0062, i.e. 49 offset-table entries. The later MAP region beginning at 0x1c040 is sample material and must not be used as the directory base.

SDDRVS command-table receipt

The retail SDDRVS.TSK image has a sixteen-entry command table at 0x1c2a. The verifier walks the authentic 68k instruction stream, accepts the observed JMP (d16,PC) and JMP abs.l forms, computes each target, and rejects targets outside the image. The receipt records the entry kind and target offset. This is a structural disassembly receipt, not a command ABI: no entry is assigned a game event, SAL selector, SCSP register meaning, or playback permission.

Host-Side Event Dispatch (Still Unmapped)

nexus_sound_set_event_selector() lets the host engine bind a Nexus_SoundEvent to a raw MAP selector, and a per-event dispatch table (g_event_selector, default -1/unmapped) looks up the bound selector at playback time. This is purely a host-owned binding mechanism — it does not assign Saturn event meaning to any selector value. Until original Saturn event→selector evidence is available, every entry stays unmapped and the dispatch table is fail-closed. The runtime receipt has a separate event_dispatch_source_verified admission bit: even a canonical SAL decode and matching SDDRVS.TSK identity remains blocked-event-dispatch until an original Saturn event→MAP trace proves the dispatch owner. MAP windows and selector bindings remain diagnostic in the meantime.

TODO

Establish the Saturn sound-driver call ABI and event→selector mapping from executable trace or disassembly evidence. Only that evidence can assign selector meaning, interpret the attribute byte, or permit audio playback.

Verification

cc -std=c99 -Wall -Wextra -O2 -Iinclude \
  tests/test_nexus_v1_sal_map_corpus.c \
  src/nexus/nexus_v1_sound.c src/nexus/nexus_v1_audio_receipt.c \
  -o /tmp/test_nexus_v1_sal_map_corpus
FIRESTAFF_NEXUS_DATA_DIR=/Users/bosse/.firestaff/data/nexus \
  /tmp/test_nexus_v1_sal_map_corpus