facts/REQUIREMENTS.md

REQUIREMENTS

facts

ring id requirement 0 001 facts must be a compiled single-file Zig CLI with no runtime dependencies beyond the OS. 0 002 facts must inspect file metadata only; it must not mutate files, execute callbacks, access the network, read hidden config, prompt, page, colorize, or emit JSON by default. 1 003 facts PATH... must emit one TSV record per path plus a header row with stable columns path, kind, size, mode, and mtime_ns. 1 003.tsv-safety facts must preserve one-line TSV records by rejecting unsupported path bytes that cannot be emitted raw in TSV fields, including tab, carriage return, and newline, before writing a path record to stdout. 1 004 With no path arguments, facts must read one path per stdin line and emit the same TSV contract. 1 004.streaming Stdin mode must stream with bounded memory: emit the TSV header before waiting for stdin EOF, process completed input lines independently, flush each completed output record before EOF, and never buffer all stdin. 1 005 Per-path runtime errors must be diagnostics on stderr, must not corrupt stdout records for other paths, and must make the process exit nonzero after flushing valid records. 1 006 facts must not filter, sort, glob, or provide an expression language; callers compose with files, grep, pick, sort, or similar stream tools. 1 007 zig build test must prove argv input, stdin input, streaming stdin behavior, TSV header shape, TSV safety rejection, size reporting, directory reporting, help output, and per-path error handling. 1 008 facts --help and facts -h must emit usage text to stdout without a TSV header and exit zero.