SplitBit-Emulator/NOTES.md

Delete me after these things are fixed

Temporary notes from the SBFS v2 and CosmOS review, in priority order.

Establish one portable path-length limit

SplitDisk carries paths up to 511 characters, while the native path machinery appears to use a 255-byte limit. Paths are not stored on disk, so this does not change the format, but the host can construct a tree addressable by a path that CosmOS cannot express in one operation.

Declare a portable CosmOS/SBFS path limit and have SplitDisk enforce it when modifying an image. The native 255-byte limit is reasonable; the important property is agreement and documentation. Component names remain limited to 22 bytes independently.

Bound the number of directory entries

The parent field is 16 bits and stores descriptor index + 1, with zero reserved for the root. Descriptor index 65535 therefore cannot be represented as a parent because adding one wraps to zero. SplitDisk currently accepts directory sizes large enough to exceed the representable parent domain.

Define and validate a maximum directory-block/entry count such that every directory entry can be named as a parent. Apply the check while formatting and mounting/reading malformed images in both implementations.

Design strengths worth preserving

• Parent-as-index-plus-one makes every version one entry a valid root child without conversion.
• Directories consume one descriptor and no data blocks, leaving the descriptor array as the complete allocation map.
• Files remain contiguous and the block allocator remains ignorant of hierarchy.
• Path resolution below the service boundary gave existing applications directories without changing their interfaces.
• The current directory is a two-byte identity rather than a stored string, and the shell restores it after applications run.
• The independent host/native implementations and byte-identical disk agreement tests are unusually strong validation of the written format.
• osFileStart/osFileWrite/osFileFetch/osFileDone provide the bounded-memory output abstraction needed by assemblers, compilers, linkers, and future sequential pipelines.