str + vec: Insert/Push family + stack-init scopes (no allocator)

Stack-init scopes (StrInitStack, VecInitStack) drop their allocator
argument -- NULL allocator is the runtime signal for "non-growable".
validate_vec / vec_aligned_size / VecAlignedOffsetAt tolerate it;
reserve_vec / deinit_vec / reduce_space_vec abort with the dedicated
"vector not growable, no allocator assigned, probably stack inited"
message. VecInitStack takes the element type as its first arg so the
macro mints `name` itself (matches StrInitStack). _Alignas(T) on the
backing struct field guarantees slot alignment for typed Vecs.
IterInitFromVec* fall back to alignment 1 on NULL allocator so a
StrIter over a stack-init Str works. No deep-copy variant: deep-copy
callbacks need an allocator, so heap-backed Vec is the answer.

Str Insert family settles on the unified L/R + *Many shape:
StrInsert/L/R single-char, StrInsertMany(Zstr) and (Zstr, len) carry
the range companion; PushBack and PushFront follow the same shape;
StrMerge defaults to L per the unsuffixed-default-is-L convention.

Migrations: Sys/Proc.c::sys_proc_read_internal now stages reads in a
stack Str + StrMergeR (the old char tmpbuf[1024] + StrPushBackMany
smell). Sys/Dns.c parsers rewritten to StrIter, matching the
Parsers/JSON.c / Parsers/KvConfig.c precedent. dns_resolve_5_zstr /
dns_resolve_4_vec_zstr go StrInitStack end-to-end. Sys/Dir.c and
Log.h::LOG_SYS_* converted to the new scope shape.

Bug fixes: Io.c::write_char_internal was producing `\x\HH` instead of
`\xHH` -- a stray backslash from `cs[3] = {'\\', c1, c2}` after `\\x`
was already emitted. Now matches the sibling pattern in the byte-loop
above. DnsResolverDeinit tolerates a zero-init or partially-failed-init
struct (validate_vec would abort on the zero-magic vec otherwise).

Conventions: CODING-CONVENTIONS.md grows a dedicated "Stack-init APIs"
section. VecCopyInit / VecCopyDeinit accessors added so tests do not
reach into Vec internals.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: brightprogrammer

Bin/Beam.c

@@ -249,7 +249,7 @@ static void log_request_summary(Allocator *alloc, Zstr client_addr, Zstr prefix_
     Scope(scope, DefaultAllocator) {
         (void)alloc;
         Str raw = StrInit(scope);
-        StrPushBackZstr(&raw, prefix_bytes);
+        StrPushBackMany(&raw, prefix_bytes);
 
         HttpRequest req = HttpRequestInit(scope);
         Zstr end = HttpRequestParse(&req, (Zstr)StrBegin(&raw));

CODING-CONVENTIONS.md

@@ -80,6 +80,28 @@ of the codebase to see them in action.
   In both cases the zero-on-take invariant holds on success AND failure.
 - **R-form (`*FromMemoryCopy` / `VecInsertR`)** copies; the caller's data
   is untouched and remains theirs.
+- **Unsuffixed default = L.** When a family has both `*L` and `*R`
+  variants, the bare unsuffixed name aliases to L: `VecInsert` ≡
+  `VecInsertL`, `ElfOpenFromMemory` is the L-form (`ElfOpenFromMemoryCopy`
+  is the explicit R counterpart). Don't dispatch an unsuffixed macro to
+  an R primitive — that inverts the convention and surprises callers.
+- **L primitives are strict-typed; R primitives are permissive-typed.**
+  L's internal `CHECK_TYPE_EQUIVALENCE` requires the source element
+  type to match the container's element type *exactly* (no const
+  promotion, no integer narrowing) — because L zeroes the source on
+  success, and that's only safe on writeable storage of the right
+  element type. R uses `CHECK_TYPE_CONVERTIBLE`, which accepts any
+  initialization-compatible source (e.g. `int` literal → `char`,
+  `char *` → `const char *`). Two consequences:
+  - Read-only / const sources (`Zstr`, `Cstr`-shaped `(Zstr, size)`)
+    *cannot* ride an L-form macro. The L primitive's strict-type
+    check rejects `const T *` for a `Vec(T)`. So a family whose
+    inputs are only ever const surfaces only R-form variants; there
+    is no L-form and no unsuffixed default — callers spell out `*R`.
+  - Integer literals like `'-'` (type `int` in C11) compile with R's
+    `CHECK_TYPE_CONVERTIBLE` but fail L's `CHECK_TYPE_EQUIVALENCE`.
+    Callers who want L semantics with literals must bind to a typed
+    lvalue first (`char c = '-'; VecInsertL(&v, c, 0)`).
 - **Prefer `Str` to `Zstr`.** `Str` carries its length and allocator
   inline; `Zstr` is a raw NUL-terminated pointer. For stored fields,
   parameters the function needs a length for, and anywhere the caller's
@@ -166,9 +188,56 @@ of the codebase to see them in action.
 - **Allocators fail loud.** Bad free, foreign pointer, state-machine
   violation → `LOG_FATAL` with a backtrace. Soft no-op returns hide bugs;
   this project would rather you crash on the spot.
-- **Stack-promote transient strings** with `StrInitStack(str, alloc, n,
-  body)` and a rough capacity. Don't spin up a fresh `HeapAllocator` to
-  hold a short-lived string.
+- **Stack-promote transient containers** with `*InitStack` (`StrInitStack`,
+  `VecInitStack`, ...) -- see the dedicated section below.
+
+## Stack-init APIs
+
+- **Stack means stack.** `*InitStack` macros take **no allocator**.
+  The backing storage is a stack array sized by the `ne` argument;
+  the container's inline allocator slot is `NULL`. If you would have
+  written `char buf[N]` and tracked its length yourself, use
+  `StrInitStack(name, N) { ... }` instead -- the lifetime, capacity,
+  and zero-on-exit are all expressed by the macro.
+- **Overflow is a contract violation, not a fallback.** Any
+  operation that would grow the container past `ne` lands in the
+  realloc path with a NULL allocator; the runtime aborts with
+  `LOG_FATAL("vector not growable, no allocator assigned, probably
+  stack inited")`. There is no spill / overflow / upstream allocator
+  argument. If a caller legitimately needs spill behaviour, that
+  caller wants an allocator-backed container, not `*InitStack`.
+- **No deep-copy callbacks on stack-init.** `copy_init` / `copy_deinit`
+  hooks take an `Allocator *` for the inner resources they own. A
+  stack-init container has no allocator and so can't pair with deep
+  copies. If you need deep-copy ownership for elements, switch to a
+  heap-backed container -- there is no `*InitStackWithDeepCopy`.
+- **For-chain scope idiom.** The body is regular code below the
+  macro, not a brace-delimited macro argument. This keeps `return` /
+  `break` / `continue` from being macro-mangled and matches `Scope(...)`
+  in `<Misra/Std/Allocator.h>`:
+
+      StrInitStack(buf, 1024) {
+          ssize_t n = read(fd, StrBegin(&buf), 1023);
+          StrResize(&buf, (size)n);
+          StrMergeR(out, &buf);
+      }
+
+  `return` / `goto` leaving the body skip the zero-on-exit cleanup
+  (a C-level limitation, not a bug). Use `break` to leave cleanly.
+- **When to use vs heap container.** Reach for `*InitStack` when the
+  size is bounded by something you control (a syscall buffer, a
+  formatted line, a per-iteration scratch space). Reach for a heap
+  container when the size is caller-controlled or unbounded
+  (parsing arbitrary input, accumulating across iterations whose
+  total is unknown). Don't paper over an unknown-size case with a
+  guessed `ne`.
+- **Don't call `Deinit` on a stack-backed handle inside the scope.**
+  The scope macro zeroes both the backing buffer and the container
+  handle on exit, which invalidates the magic value; after the
+  scope, any operation on the handle (including a stray
+  `StrDeinit` / `VecDeinit`) trips `validate_vec` with the
+  `Either uninitialized or corrupted!` message. Inside the scope,
+  there is no separate teardown to run -- the macro IS the teardown.
 
 ## Libc-free mindset
 
@@ -229,6 +298,20 @@ of the codebase to see them in action.
   (`<Misra/Std/Container/Str/Access.h>`), and the corresponding `Vec`
   ones. Direct field access is reserved for the container's own
   implementation.
+- **`_Generic` arm bodies must have uniform shape.** C11 type-checks
+  *every* arm's body (not just the selected one). An arm that
+  dereferences (`((T *)(val))->field`) and an arm that treats `val`
+  as a value (`(char)(val)`) cannot coexist in the same `_Generic`:
+  when `val` has the *other* arm's type, the non-selected arm fails
+  to type-check (CHECK_TYPE_EQUIVALENCE / CHECK_TYPE_CONVERTIBLE
+  fires inside the unreached arm's macro expansion). Concretely:
+  do not mix single-value arms (`char:`, `int:`) with pointer-deref
+  arms (`Str *:`, `Zstr:`) in one `_Generic`. Split into two macros
+  — one for the single-value shape, one for the range / pointer
+  shape — and give them distinct names (e.g. `*Insert` for single,
+  `*InsertMany` for range). The unified-macro-with-mixed-shapes
+  pattern only works when every arm body has the same pointer-deref
+  or pointer-cast shape.
 
 ## Macro hygiene
 

Fuzz/Harness/Str.c

@@ -193,7 +193,7 @@ void fuzz_str(Str *str, StrFunction func, const uint8_t *data, size_t *offset, s
             if (VecLen(str) > 0 && *offset + 1 <= size) {
                 char *cstr = generate_cstring(data, offset, size, 20);
                 if (cstr) {
-                    int result = StrCmpCstr(str, cstr, strlen(cstr));
+                    int result = StrCmp(str, cstr, strlen(cstr));
                     (void)result; // Suppress unused variable warning
                     free(cstr);
                 }
@@ -205,7 +205,7 @@ void fuzz_str(Str *str, StrFunction func, const uint8_t *data, size_t *offset, s
             if (VecLen(str) > 0 && *offset + 1 <= size) {
                 char *zstr = generate_cstring(data, offset, size, 20);
                 if (zstr) {
-                    int result = StrCmpZstr(str, zstr);
+                    int result = StrCmp(str, zstr);
                     (void)result; // Suppress unused variable warning
                     free(zstr);
                 }
@@ -216,7 +216,7 @@ void fuzz_str(Str *str, StrFunction func, const uint8_t *data, size_t *offset, s
         case STR_FIND_STR : {
             if (VecLen(str) > 0) {
                 Str   temp  = generate_str_from_input(data, offset, size, 10, alloc);
-                char *found = StrFindStr(str, &temp);
+                char *found = StrFind(str, &temp);
                 (void)found; // Suppress unused variable warning
                 StrDeinit(&temp);
             }
@@ -227,7 +227,7 @@ void fuzz_str(Str *str, StrFunction func, const uint8_t *data, size_t *offset, s
             if (VecLen(str) > 0 && *offset + 1 <= size) {
                 char *zstr = generate_cstring(data, offset, size, 10);
                 if (zstr) {
-                    char *found = StrFindZstr(str, zstr);
+                    char *found = StrFind(str, zstr);
                     (void)found; // Suppress unused variable warning
                     free(zstr);
                 }
@@ -239,7 +239,7 @@ void fuzz_str(Str *str, StrFunction func, const uint8_t *data, size_t *offset, s
             if (VecLen(str) > 0 && *offset + 1 <= size) {
                 char *cstr = generate_cstring(data, offset, size, 10);
                 if (cstr) {
-                    char *found = StrFindCstr(str, cstr, strlen(cstr));
+                    char *found = StrFind(str, cstr, strlen(cstr));
                     (void)found; // Suppress unused variable warning
                     free(cstr);
                 }