MatchFirst/MatchNext diverge from real Kickstart 3.1: extra leading row, missing trailing row, and a directory argument enumerating the volume root

[sidick]

Found while arbitrating #58's APF_DirChanged question on real hardware (see that issue for the setup and for the DirChanged conclusion, which volamos gets right). These are separate, and here volamos diverges from real hardware.

Setup

amitools' test/bin/dos_match_gcc — a real compiler-built binary that sets ap_Flags = APF_DOWILD | APF_DODIR, ap_Strlen = 255, then prints fib_FileName, ap_Buf, fib_Size and ap_Flags once per MatchFirst/MatchNext — over an AmiBake os3.1.4 corpus. Real oracle: Kickstart 3.1 (40.63), --model A600, corpus mounted via a Copperline [[filesys]] host-directory mount, guest output redirected by its own Startup-Sequence to a host-visible file.

Finding A: the row sequence differs at both ends

Argument sys: to both engines.

Real KS 3.1 (first row, then the last two):

C sys:C 3328 65
...entries, all flags 1...
 sys: 0 73
 sys: 1056 9

volamos:

 sys: 0 5          <- extra row real hardware does not produce
C sys:C 0 65
...entries, all flags 1...
 sys: 0 73
                   <- real hardware's second trailing row is absent

Two differences:

1. volamos produces an extra leading row reporting the volume root itself, with ap_Flags still at the caller's 5 (APF_DOWILD|APF_DODIR). Real MatchFirst returns the first entry (C) and has already consumed APF_DODIR — its row is 65, with the 4 bit gone.
2. Real hardware reports the finished directory twice at the end (73 = DOWILD|DIDDIR|DirChanged, then 9 = DOWILD|DIDDIR); volamos reports it once (73).

Both change the number of iterations a correct AnchorPath caller observes, so a program that counts matches, or that drives a UI off the iteration sequence, sees something different under volamos.

Finding B: a directory argument is interpreted differently (needs investigation)

With a nested tree at SYS:tree (a/aa/file1, a/ab/file2, b/file3, file4) and the argument SYS:tree:

• volamos scans SYS:tree, as you would expect:

  tree SYS:tree 0 5
  a SYS:tree/a 0 65
  b SYS:tree/b 0 1
  file4 SYS:tree/file4 2 1
  tree SYS:tree/ 0 73
  

• Real KS 3.1 instead enumerates the volume root SYS: — every one of C, Classes, Devs, ... including tree as a single ordinary entry — and ends with the same two SYS: rows as the sys: case.

Verified this is not a quoting artifact: the unquoted SYS:dos_match SYS:tree form gives the identical result, and the Startup-Sequence and directory tree were both confirmed on the host side afterwards.

I do not have a confident explanation for this, and I would rather record the measurement than guess a mechanism. APF_DOWILD is documented in dos/dosasl.h only as "User option ALL", which may be the relevant lever — real MatchFirst may treat a non-wildcard path plus DOWILD quite differently from volamos's model. It is also possible Findings A and B are two symptoms of one underlying difference in how real MatchFirst resolves a non-wildcard pattern, in which case "extra leading row" and "missing trailing row" are the wrong frame for A.

That needs settling before changing anything: volamos's AnchorPath implementation is load-bearing for the real List, Copy, Delete and Rename binaries, all of which currently work end to end, so a semantic change here risks regressing verified behaviour.

Suggested next steps

• Characterise real MatchFirst's treatment of a non-wildcard pattern under APF_DOWILD on hardware: with and without APF_DOWILD, with and without APF_DODIR, on a plain directory, on a volume root, and on an explicit wildcard — a small matrix rather than one case.
• Only then decide whether Finding A is its own bug or a consequence of Finding B.
• Re-verify the real List/Copy/Delete/Rename corpus after any change, since those are the regression surface.
• fixtures/matchflags (added alongside this work) exercises a nested scan and prints per-entry flags, which is the right shape for the matrix above — but note it currently hangs/faults on real hardware (the guest ends up at a "Please insert volume SYS" requester with an empty result file) while working fine under volamos. It needs hardening before it can serve as a hardware oracle; dos_match_gcc was used for every hardware measurement here instead.

Related: #58 (the APF_DirChanged arbitration that surfaced this), #46 (the earlier ap_Buf fix), #60 (own corpus).