code/inventory/SCANNER-API.md

@@ -166,18 +166,31 @@ the `WL2:D` channel by any tried method:
 - `p_read(h, buf, len)` (synchronous, with length) — no data.
 - `p_ioc(h, P_FREAD, &stat, buf, &len)` + trigger + `p_iowait()` (async) — no data.
 
-The retrieval logic in `SCANNER.DYL`/`SCANAPP` uses relocatable code that does not
-disassemble cleanly without the EPOC16 executable segment map, builds decoder
-command frames (`0xff 0xee …` at `channel+4+0x13`), and performs read/write on a
-**separate handle** (a driver global), suggesting the decoded result is delivered
-by a mechanism other than a plain `P_FREAD` on `WL2:D` (e.g. an auxiliary channel
-or an installed callback / active object). Extracting it reliably needs either:
+The retrieval logic in `SCANNER.DYL`/`SCANAPP` fetches the decoded data on a
+**separate handle** (a driver global, e.g. `[0x13b5]`) obtained through
+**OS-service stubs** of the form `mov ah,N; int 0x84/0x85/0x86/0x87; ret` — not a
+plain `P_FREAD` on the `WL2:D` control channel. This resolves an earlier puzzle:
+the SIBO executive uses **different register conventions per interrupt vector** —
+the `int 0x84` service family passes the function in `AH`, whereas the `int 0xCF`
+I/O executive uses `CL`.
 
-1. The **Workabout MX C SDK** `SCANNER.DYL` header/category (what `SCANAPP` was
-   built against) — the clean answer; or
-2. A full RE effort: parse the SIBO ROM/executable format, load `SCANNER.DYL` at
-   its correct segment base, and trace the retrieval path — large, and every
-   hypothesis costs an on-device build/test cycle.
+`SCANNER.DYL` is an **object-oriented ROM library (a DYL)**. This strongly
+suggests the scanner is driven by **creating a scanner object and sending it
+messages** (the OLIB/OO model), not by raw device I/O on `WL2:D`. That would
+explain why every raw `WL2:D` read returned no data — wrong paradigm.
+
+**Confirmed working on device:** `p_open("WL2:D")` + control ops `6` then `7`
+trigger the laser and a good decode (green LED). Only *retrieving* the decoded
+bytes is unsolved.
+
+To close it, one of:
+1. The **Workabout MX C SDK** `SCANNER.DYL` header / OO category definition (what
+   `SCANAPP` was built against) — the clean answer, and likely the only practical
+   one, because the interface is object-oriented.
+2. A deep RE effort under MAME (`psionwamx`): automate the UI to launch `SCANAPP`,
+   breakpoint the read routine, and trace it. Caveats: MAME cannot inject a real
+   barcode (no laser input), so only the read *setup* is observable in emulation;
+   the reconstructed sequence must still be validated on the physical device.
 
 ## Error codes seen (from `epocdefs.h`)