AntOS Library — fs (reference)

The fs library's design and native core. fs is where the AntOS filesystem extras live — the stuff standard Lua never had (directory listing, stat, mkdir, tags, catalogue queries) — kept off os/io so those stay exactly standard. The script-facing API is luau_fs.

What it is

fs covers directory and metadata operations, the DBFS tag/metadata surface, and catalogue queries. All of it is AntOS-specific (no standard equivalent), so it gets its own namespace rather than being bolted onto os/io. File content reading/writing stays in io; fs is metadata, structure, and search.

Design notes

• Auto-cataloguing lives below fs, in the DBFS/VFS layer — every create/update/delete/rename on D:, from any source (io, C, the network, a command), writes the catalogue row in the same SQLite transaction as the data. fs's tag/meta/query calls are wrappers over those catalogue tables; the dir/stat calls wrap the VFS (antos_library_design §7).
• Tags/queries are D:-only — off DBFS they return nil, err, so intent-to-tag fails loudly. Tag lifetime: system columns always fresh, user tags sticky across content rewrites, cleared on delete (antos_library_design §12).
• For raw SQL and custom application tables, db exposes the same DBFS database directly; fs.query is the safe, shaped catalogue subset over it.
• No device surface, ever. fs describes volumes that already exist; it does not create, drive or talk to the hardware behind them. The worked case is floppy, whose flux calls were considered for fs and deliberately kept out — a library holding both "list a directory" and "read raw magnetic transitions" no longer has a describable purpose. The two meet at exactly one point: floppy mounts a decoded disk, and fs then sees an ordinary catalogued volume. The same reasoning that keeps os/io standard keeps fs narrow.

Native core — libantos_fs

libantos_fs sits on the VFS and the DBFS catalogue tables — plain C, no Luau. A file created from C or over the network is catalogued identically, because the catalogue write is in the VFS, not the binding.

Related

• luau_fs — the script API · antos_io (file content) · antos_floppy (device access, kept out of here) · antos_library_design · Filesystem · NFC · AntOS Libraries hub