ULTIMATEEXPERIMENTSCommodore 64 · Work in progress

ReadyFS Path Research and Translation Notes

Why the public syntax is not native DOS syntax

C64 OS combines device, partition, filename, and path as device:partition:filename:path. Its documentation explains that filename is placed before the path partly so a narrow status display keeps the filename visible. That is useful for its UI, but it makes a typed hierarchical shell path harder to read and makes an image-file boundary implicit.

ReadyFS instead keeps the hierarchy in traversal order:

The optional .partition numeric suffix is reserved for CMD/SD2IEC-compatible IEC drivers. For native SD2IEC, 10.1:/ selects partition 1 on device 10, while 10.2:/ selects an existing partition 2 on that same device. The suffix and IEC address are separate decimal numbers. Omitting the suffix, as in 10:/, uses the device's current partition, queried and pinned for each operation; internal zero represents current/default, not a fixed data partition 0. IEC 10: PARTITIONS lists available partitions. Explicit paths do not change the current selection; IEC 10: PARTITION N --SELECT deliberately does. Parsing this form does not grant directory capability: the detected driver must explicitly support partitioned paths before listing or mutation. See native SD2IEC support for the current implementation.

Translation rules

The public path is always normalized and absolute. A backend may temporarily change its own current directory, but every transaction starts by reasserting the public absolute location; ReadyFS never treats backend current-directory state as durable shell state.

CMD/SD2IEC use a DOS command-string grammar in which a partition and directory path precede a colon-separated leaf. SD2IEC also treats a disk image as a directory for CD, and leaving it requires a separate parent/unmount command. ReadyFS does not leak that stateful behavior into its public path. ! records the transition from host file to contained filesystem, so planning can reject an unsupported cross-image operation before changing device state.

The pure CMD/SD2IEC translator is host-harness-proven for the following commands. The same source cc65-compiles into the cached RFCMDPATH sidecar ($B600, $FFD bytes) on the overlay lab D81. Boot loads it into REU slot 5, verifies its ABI, runs a compact $:pattern translation self-test, and restores the matcher before the prompt. The larger callable VICE suite proves file-open, rename, image-mount, two-command-unmount, and matcher restoration. The callable native OP PATH [DEST] diagnostic runs from the help sidecar, swaps into CMD path through resident scratch, restores help, prints the exact native result, and restores the matcher. A separate RFDRIVE sidecar classifies bounded status-channel replies while the resident exclusively owns KERNAL IEC I/O. probe iec DRIVE: is proven in VICE, but translated mutating commands are not issued until the detected profile explicitly grants their capabilities:

Detected IEC profiles are stored per device in session REU $0888-$08E3 as individually marked records. The registry is cleared at application boot and every lookup validates both marker and device number. profile iec 8: mount therefore answers from a durable, explicit capability record rather than the last transient status buffer. The current matrix requires P for open and scratch, P+F for directory and folder/rename operations, and P+F+I for image mount/unmount.

ReadyFS Native operation
8:/RF* --native-pattern $:RF* (flat read-only directory selection)
11.3:/games/HELLO.PRG 3//games/:HELLO.PRG
directory 11.3:/games/tools $3//games/tools/
scratch 11.3:/games/OLD.SEQ S3//games/:OLD.SEQ
mkdir 11.3:/games/newdir MD3//games/:newdir
rmdir 11.3:/games/old RD3//games/:old
rename old to new R3//archive/:NEW.SEQ=3//games/:OLD.SEQ (new=old)
mount 11.3:/games/demo.d64 CD3//games/demo.d64
unmount partition root CD//, then CD plus PETSCII back-arrow $5F
11.3:/games/demo.d64!/HELLO rejected as stateful until mount/open/restore transaction support exists
s3:/games/HELLO SoftwareIEC KERNAL name 3:/games/HELLO on discovered bus

The harness also rejects cross-device/cross-partition rename, partitionless legacy IEC paths, non-IEC endpoints, unsupported image extensions, components over 16 bytes, and image-contained access that would require hidden mutable device state. make readyfs-host-tests compiles and runs this contract.

Length and capability policy

Native-pattern action contract

Native patterns may eventually select copy, move, and delete inputs, but they must never be forwarded as a wildcard mutation such as S:RF*. The accepted execution model is:

  1. Translate and open the backend pattern only as a read-only directory query.
  2. Ignore the directory header and serialize every exact returned filename, type, and block estimate into the existing bounded REU action plan. Hitting the entry limit invalidates the whole plan; it never means “apply the first N”.
  3. Apply --include/--exclude, if present, only after native enumeration and against each complete ReadyFS relative stem. This keeps backend selection and shell filtering distinct and inspectable.
  4. --whatif prints every exact selected target plus totals and performs no write, scratch, rename, mount, or directory-changing command.
  5. A real run requires --apply, displays the complete selection, and freezes those exact names before execution. Bare --native-pattern remains denied even with --force/--yes. Each frozen target then uses the normal staged copy/move or exact-name delete path with RFJ1-before-ACK and stop/continue policy; the wildcard is never reissued as a mutation command.
  6. Copy/move require a directory destination when more than one source is selected. Directories and unsupported REL transfers reject the entire first-generation plan before mutation; per-type expansion comes only with dedicated evidence.

Preview syntax is copy 8:/RF* 9:/ --native-pattern --whatif, move ..., and delete 8:/RF* --native-pattern --whatif; execution replaces --whatif with the explicit --apply opt-in (plus normal conflict/confirmation options). Users do not add --recursive merely because the implementation reuses the batch controller. In 171906, resident IEC enumeration feeds exact names and types through the backend/matcher/recursive sidecars; filtered planning stays zero-write, singleton native delete succeeds, and native copy/move cross from IEC8 to IEC9 with exact byte/postcondition checks. Parsed RFJ1 dumps contain only RFNC1, RFNC2, and RFNM1 exact-name actions. Wildcard scratch, write, and rename commands remain forbidden. Regular IEC collection destinations must be the flat root; 171852 additionally proves that a matched REL $13 entry rejects the entire native plan with the destination still absent.

Sources

SoftwareIEC host-file/type findings on firmware 3.14

SoftwareIEC directory-breadth boundary

The marker-owned run root eventually accumulated many deliberately preserved diagnostic folders. Firmware 3.14 then stopped entering newly appended root folders through direct CD: even though UltimateDOS listed them. Seeding rf094315/rfseed.seq and rebooting with exact SoftIEC config equality did not change the result. Creating a fresh child under already visible, uncrowded rf091800 worked immediately, including a nested directory below it. This aligns with the truncated FAT/BASIC-directory behavior: path design cannot assume every raw host entry is reachable through SoftwareIEC at arbitrary parent breadth. Future integration should expose a capability/refresh boundary and prefer dedicated shallow SoftIEC-visible roots.