parsers + file: Buf migration, _Generic type safety, encapsulation cleanup

Big refactor that lands several related cleanups in one commit:

1. Parser structs migrate from `Allocator * + u8 *data + size data_size`
   to a single `Buf data` field. ElfFile, MachoFile, PeFile, PdbFile all
   now own a Buf and free it through `BufDeinit`. The L-form
   `*_open_from_memory` signature drops to `(<Foo>File *out, Buf *in)`:
   parser snapshots the Buf and MemSets the caller's view to zero, so
   any post-call use is a fresh empty Buf instead of a stale alias.
   No data copy in the L-form (only the 4 struct fields move). The
   R-form `_copy` still does a MemCopy through a fresh Buf, no change
   to its contract.

2. `FileRead(File *, Buf *)` overload added next to the existing Str
   form. Five parser callers (Elf/MachO/Pe/Pdb/Http) slurp into Buf
   now -- semantically correct for binary inputs, and the cast +
   manual-disassembly dance is gone. `BufFmt` declarations moved out
   of Buf.h into Io.h (they're an I/O concern; Buf.h was pulling Io.h
   transitively which formed a File.h <-> Buf.h cycle).

3. `_Generic` type safety: 14 path-API macros (FileOpen, FileGetSize,
   File/DirRemove, DirCreate/CreateAll/RemoveAll, DirGetContents, and
   the four parser `_Open` overloads) previously had a `default:` arm
   that silently cast any input to `const char *` -- passing an
   `int *` or struct pointer compiled clean. Replaced with explicit
   `char *:` and `const char *:` associations so unsupported types
   now fail to compile (no matching `_Generic` association). `IOFMT`
   and `ARG_TARGET` keep their `default:` arms intentionally -- both
   route to runtime LOG_FATAL sentinels (`UnsupportedType` /
   `ARG_KIND_INVALID`), documented in their headers.

4. `BufAllocator(b)` accessor macro added; ~60 sites of direct
   `b->length` / `b->data` / `b->allocator` access in parsers, Http,
   KvConfig, MachoCache replaced with `BufLength` / `BufData` /
   `BufAllocator` / `StrLen` / `StrBegin` / `StrCharAt`. Container
   fields are accessed only inside the container's own `.c`; outside
   code goes through the public macro surface.

5. `FileOpenTemp` drops its `prefix` argument -- the name is now just
   `Prng64()` rendered as 16-hex, file lands in CWD. Removes the
   `_Generic`-on-path complexity entirely (no string-shaped input to
   dispatch on). Iter test files include Buf.h directly now that
   Buf.h doesn't transitively pull it through Iter.h's chain.

Verified:
  Linux sanitised:    104/104 OK
  Mac sanitised:      99/99 OK in 40s wall
  Mac freestanding:   99/99 OK in 19s wall
  Mac libc-diet:      beam + resolve dyld-only (no libSystem refs)

Author: brightprogrammer

Include/Misra/Parsers/Elf.h

@@ -18,6 +18,7 @@
 #define MISRA_PARSERS_ELF_H
 
 #include <Misra/Std/Allocator.h>
+#include <Misra/Std/Container/Buf.h>
 #include <Misra/Std/Container/Str.h>
 #include <Misra/Std/Container/Vec.h>
 #include <Misra/Types.h>
@@ -174,9 +175,7 @@ typedef Vec(ElfSymbol) ElfSymbols;
 ///                     (validated by the resolver before use).
 ///
 typedef struct ElfFile {
-    Allocator  *allocator;
-    u8         *data;
-    size        data_size;
+    Buf         data;
     ElfHeader   header;
     ElfSections sections;
     ElfSymbols  symbols;
@@ -209,56 +208,49 @@ bool elf_file_open(ElfFile *out, const char *path, Allocator *alloc);
         (path),                                                                                                        \
         Str *: elf_file_open((out), ((Str *)(path))->data, MisraScope),                                                \
         const Str *: elf_file_open((out), ((const Str *)(path))->data, MisraScope),                                    \
-        default: elf_file_open((out), (const char *)(path), MisraScope)                                                \
+        char *: elf_file_open((out), (const char *)(path), MisraScope),                                                \
+        const char *: elf_file_open((out), (const char *)(path), MisraScope)                                           \
     )
 #define ElfFileOpen_3(out, path, alloc)                                                                                \
     _Generic(                                                                                                          \
         (path),                                                                                                        \
         Str *: elf_file_open((out), ((Str *)(path))->data, ALLOCATOR_OF(alloc)),                                       \
         const Str *: elf_file_open((out), ((const Str *)(path))->data, ALLOCATOR_OF(alloc)),                           \
-        default: elf_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc))                                       \
+        char *: elf_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc)),                                       \
+        const char *: elf_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc))                                  \
     )
 
 ///
 /// Parse an ELF object from an in-memory byte range -- **L-value /
 /// ownership-transfer form** (mirrors `VecInsertL`).
 ///
-/// The `data` parameter is `u8 **` -- a pointer to the caller's
-/// pointer -- precisely because ownership is moving. After the call
-/// returns, `*data == NULL`: the caller's variable has been zeroed
-/// to make use-after-transfer impossible. The parser holds the
-/// original pointer internally and frees it through `alloc` on
-/// `ElfFileDeinit`. This invariant is the same on success and failure
-/// -- on parse failure the parser still frees the bytes and still
-/// nulls `*data`.
+/// Takes the caller's `Buf` by pointer. The parser snapshots the Buf
+/// internally and zeroes the caller's `*in` so any post-call use sees
+/// an empty Buf instead of a stale alias. The parser then owns the
+/// bytes and the buffer's allocator; both are released by
+/// `ElfFileDeinit`. The zero-on-take invariant holds on both success
+/// and failure -- on parse failure the parser still consumed the Buf,
+/// just frees it through the carried allocator before returning.
 ///
 /// USAGE:
-///   u8 *buf = my_buffer;       // buffer allocated through `alloc`
-///   ElfFileOpenFromMemory(&elf, &buf, n, &alloc);
-///   // buf == NULL here -- compiler can't enforce, but a follow-up
-///   // dereference will SIGSEGV instead of using freed memory.
+///   Buf buf = BufInit(&alloc);
+///   FileRead(&f, &buf);
+///   ElfFileOpenFromMemory(&elf, &buf);
+///   // buf is now {NULL, 0, 0, NULL} -- safe to drop on stack.
 ///
-/// out[out]      : Populated on success.
-/// data[in,out]  : Address of the caller's `u8 *` holding the bytes.
-///                 `*data` MUST be non-NULL and MUST have been
-///                 produced by `alloc`. After the call, `*data` is
-///                 NULL (success or failure).
-/// data_size[in] : Length of the buffer pointed to by `*data`.
-/// alloc[in]     : Allocator that produced `*data` and that will back
-///                 the section / symbol vectors.
-///
-/// SUCCESS : Returns true; `out` owns the bytes; `*data == NULL`.
-/// FAILURE : Returns false; the bytes have been freed through `alloc`;
-///           `*data == NULL`; `out` is left zeroed.
+/// out[out]    : Populated on success.
+/// in[in,out]  : Pointer to the caller's `Buf`. `in->data` must be
+///               non-NULL and `in->allocator` must be set. After the
+///               call, `*in` is zeroed (success or failure).
+///
+/// SUCCESS : Returns true; `out` owns the bytes; `*in` is zeroed.
+/// FAILURE : Returns false; the bytes have been freed; `*in` is
+///           zeroed; `out` is left zeroed.
 ///
 /// TAGS: Parser, ELF, Memory, Ownership
 ///
-bool elf_file_open_from_memory(ElfFile *out, u8 **data, size data_size, Allocator *alloc);
-#define ElfFileOpenFromMemory(...) MISRA_OVERLOAD(ElfFileOpenFromMemory, __VA_ARGS__)
-#define ElfFileOpenFromMemory_3(out, dataref, data_size)                                                               \
-    elf_file_open_from_memory((out), (dataref), (data_size), MisraScope)
-#define ElfFileOpenFromMemory_4(out, dataref, data_size, alloc)                                                        \
-    elf_file_open_from_memory((out), (dataref), (data_size), ALLOCATOR_OF(alloc))
+bool elf_file_open_from_memory(ElfFile *out, Buf *in);
+#define ElfFileOpenFromMemory(out, in) elf_file_open_from_memory((out), (in))
 
 ///
 /// Parse an ELF object from an in-memory byte range -- **R-value /

Include/Misra/Parsers/MachO.h

@@ -23,6 +23,7 @@
 #define MISRA_PARSERS_MACHO_H
 
 #include <Misra/Std/Allocator.h>
+#include <Misra/Std/Container/Buf.h>
 #include <Misra/Std/Container/Vec.h>
 #include <Misra/Types.h>
 
@@ -99,9 +100,7 @@ typedef Vec(MachoSymbol) MachoSymbols;
 /// - symbols       : Entries from LC_SYMTAB; may be empty if stripped.
 ///
 typedef struct MachoFile {
-    Allocator    *allocator;
-    u8           *data;
-    size          data_size;
+    Buf           data;
     u32           cputype;
     MachoFileType filetype;
     u8            uuid[16];
@@ -128,40 +127,41 @@ bool macho_file_open(MachoFile *out, const char *path, Allocator *alloc);
         (path),                                                                                                        \
         Str *: macho_file_open((out), ((Str *)(path))->data, MisraScope),                                              \
         const Str *: macho_file_open((out), ((const Str *)(path))->data, MisraScope),                                  \
-        default: macho_file_open((out), (const char *)(path), MisraScope)                                              \
+        char *: macho_file_open((out), (const char *)(path), MisraScope),                                              \
+        const char *: macho_file_open((out), (const char *)(path), MisraScope)                                         \
     )
 #define MachoFileOpen_3(out, path, alloc)                                                                              \
     _Generic(                                                                                                          \
         (path),                                                                                                        \
         Str *: macho_file_open((out), ((Str *)(path))->data, ALLOCATOR_OF(alloc)),                                     \
         const Str *: macho_file_open((out), ((const Str *)(path))->data, ALLOCATOR_OF(alloc)),                         \
-        default: macho_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc))                                     \
+        char *: macho_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc)),                                     \
+        const char *: macho_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc))                                \
     )
 
 ///
 /// Parse a Mach-O image from an in-memory byte range -- **L-value /
 /// ownership-transfer form** (mirrors `VecInsertL`).
 ///
-/// `data` is `u8 **`: ownership is moving from caller to parser. On
-/// entry `*data` is the caller's buffer (allocated through `alloc`);
-/// on exit (success OR failure) `*data == NULL`. Calling code:
+/// Takes the caller's `Buf` by pointer. The parser snapshots the Buf
+/// and zeroes the caller's `*in` so any post-call use is an empty Buf
+/// rather than a stale alias. Allocator comes from the Buf. The
+/// zero-on-take invariant holds on success and failure.
 ///
-///   u8 *buf = my_buffer;
-///   MachoFileOpenFromMemory(&m, &buf, n, &alloc);
-///   // buf == NULL afterwards.
+/// USAGE:
+///   Buf buf = BufInit(&alloc);
+///   FileRead(&f, &buf);
+///   MachoFileOpenFromMemory(&m, &buf);
+///   // buf is now zeroed.
 ///
-/// SUCCESS : Returns true; `out` owns the bytes; `*data == NULL`.
-/// FAILURE : Returns false; the bytes have been freed through `alloc`;
-///           `*data == NULL`; `out` is left zeroed.
+/// SUCCESS : Returns true; `out` owns the bytes; `*in` is zeroed.
+/// FAILURE : Returns false; the bytes have been freed; `*in` is zeroed;
+///           `out` is left zeroed.
 ///
 /// TAGS: Parser, MachO, Memory, Ownership
 ///
-bool macho_file_open_from_memory(MachoFile *out, u8 **data, size data_size, Allocator *alloc);
-#define MachoFileOpenFromMemory(...) MISRA_OVERLOAD(MachoFileOpenFromMemory, __VA_ARGS__)
-#define MachoFileOpenFromMemory_3(out, dataref, data_size)                                                             \
-    macho_file_open_from_memory((out), (dataref), (data_size), MisraScope)
-#define MachoFileOpenFromMemory_4(out, dataref, data_size, alloc)                                                      \
-    macho_file_open_from_memory((out), (dataref), (data_size), ALLOCATOR_OF(alloc))
+bool macho_file_open_from_memory(MachoFile *out, Buf *in);
+#define MachoFileOpenFromMemory(out, in) macho_file_open_from_memory((out), (in))
 
 ///
 /// Parse a Mach-O image from an in-memory byte range -- **R-value /

Include/Misra/Parsers/Pdb.h

@@ -26,6 +26,7 @@
 #define MISRA_PARSERS_PDB_H
 
 #include <Misra/Std/Allocator.h>
+#include <Misra/Std/Container/Buf.h>
 #include <Misra/Std/Container/Vec.h>
 #include <Misra/Types.h>
 
@@ -81,9 +82,7 @@ typedef struct PdbInfo {
 ///                 `PdbFileOpen[FromMemory]`.
 ///
 typedef struct PdbFile {
-    Allocator   *allocator;
-    u8          *data;
-    size         data_size;
+    Buf          data;
     u32          block_size;
     u32          num_streams;
     PdbInfo      info;
@@ -123,14 +122,16 @@ bool pdb_file_open(PdbFile *out, const char *path, Allocator *alloc);
         (path),                                                                                                        \
         Str *: pdb_file_open((out), ((Str *)(path))->data, MisraScope),                                                \
         const Str *: pdb_file_open((out), ((const Str *)(path))->data, MisraScope),                                    \
-        default: pdb_file_open((out), (const char *)(path), MisraScope)                                                \
+        char *: pdb_file_open((out), (const char *)(path), MisraScope),                                                \
+        const char *: pdb_file_open((out), (const char *)(path), MisraScope)                                           \
     )
 #define PdbFileOpen_3(out, path, alloc)                                                                                \
     _Generic(                                                                                                          \
         (path),                                                                                                        \
         Str *: pdb_file_open((out), ((Str *)(path))->data, ALLOCATOR_OF(alloc)),                                       \
         const Str *: pdb_file_open((out), ((const Str *)(path))->data, ALLOCATOR_OF(alloc)),                           \
-        default: pdb_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc))                                       \
+        char *: pdb_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc)),                                       \
+        const char *: pdb_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc))                                  \
     )
 
 ///
@@ -151,12 +152,8 @@ bool pdb_file_open(PdbFile *out, const char *path, Allocator *alloc);
 ///
 /// TAGS: Parser, PDB, Memory, Ownership
 ///
-bool pdb_file_open_from_memory(PdbFile *out, u8 **data, size data_size, Allocator *alloc);
-#define PdbFileOpenFromMemory(...) MISRA_OVERLOAD(PdbFileOpenFromMemory, __VA_ARGS__)
-#define PdbFileOpenFromMemory_3(out, dataref, data_size)                                                               \
-    pdb_file_open_from_memory((out), (dataref), (data_size), MisraScope)
-#define PdbFileOpenFromMemory_4(out, dataref, data_size, alloc)                                                        \
-    pdb_file_open_from_memory((out), (dataref), (data_size), ALLOCATOR_OF(alloc))
+bool pdb_file_open_from_memory(PdbFile *out, Buf *in);
+#define PdbFileOpenFromMemory(out, in) pdb_file_open_from_memory((out), (in))
 
 ///
 /// Open and parse a PDB from an in-memory byte range -- **R-value /

Include/Misra/Parsers/Pe.h

@@ -17,6 +17,7 @@
 #define MISRA_PARSERS_PE_H
 
 #include <Misra/Std/Allocator.h>
+#include <Misra/Std/Container/Buf.h>
 #include <Misra/Std/Container/Vec.h>
 #include <Misra/Types.h>
 
@@ -94,9 +95,7 @@ typedef struct PeCodeViewInfo {
 /// - codeview      : CodeView debug record, if present.
 ///
 typedef struct PeFile {
-    Allocator     *allocator;
-    u8            *data;
-    size           data_size;
+    Buf            data;
     PeMachine      machine;
     bool           is_pe32_plus;
     u64            image_base;
@@ -125,14 +124,16 @@ bool pe_file_open(PeFile *out, const char *path, Allocator *alloc);
         (path),                                                                                                        \
         Str *: pe_file_open((out), ((Str *)(path))->data, MisraScope),                                                 \
         const Str *: pe_file_open((out), ((const Str *)(path))->data, MisraScope),                                     \
-        default: pe_file_open((out), (const char *)(path), MisraScope)                                                 \
+        char *: pe_file_open((out), (const char *)(path), MisraScope),                                                 \
+        const char *: pe_file_open((out), (const char *)(path), MisraScope)                                            \
     )
 #define PeFileOpen_3(out, path, alloc)                                                                                 \
     _Generic(                                                                                                          \
         (path),                                                                                                        \
         Str *: pe_file_open((out), ((Str *)(path))->data, ALLOCATOR_OF(alloc)),                                        \
         const Str *: pe_file_open((out), ((const Str *)(path))->data, ALLOCATOR_OF(alloc)),                            \
-        default: pe_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc))                                        \
+        char *: pe_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc)),                                        \
+        const char *: pe_file_open((out), (const char *)(path), ALLOCATOR_OF(alloc))                                   \
     )
 
 ///
@@ -153,12 +154,8 @@ bool pe_file_open(PeFile *out, const char *path, Allocator *alloc);
 ///
 /// TAGS: Parser, PE, Memory, Ownership
 ///
-bool pe_file_open_from_memory(PeFile *out, u8 **data, size data_size, Allocator *alloc);
-#define PeFileOpenFromMemory(...) MISRA_OVERLOAD(PeFileOpenFromMemory, __VA_ARGS__)
-#define PeFileOpenFromMemory_3(out, dataref, data_size)                                                                \
-    pe_file_open_from_memory((out), (dataref), (data_size), MisraScope)
-#define PeFileOpenFromMemory_4(out, dataref, data_size, alloc)                                                         \
-    pe_file_open_from_memory((out), (dataref), (data_size), ALLOCATOR_OF(alloc))
+bool pe_file_open_from_memory(PeFile *out, Buf *in);
+#define PeFileOpenFromMemory(out, in) pe_file_open_from_memory((out), (in))
 
 ///
 /// Parse a PE image from an in-memory byte range -- **R-value /