cut noise from 0.15 notes after critical review

- arraylist: focus on ownership (toOwnedSlice vs deinit), not "remember allocator"
- io: keep core patterns + tls quirk, add http.Client, delete history lesson
- build: just the 0.15 change and hash trick, delete boilerplate
- comptime: generalizable patterns, not zql description
- concurrency: design decisions (atomics vs mutex), not std.Thread syntax

-182 lines, mostly redundant/obvious content

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

languages/ziglang/0.15/README.md

···
 # zig 0.15
 
-[release notes](https://ziglang.org/download/0.15.1/release-notes.html) · [migration guide](https://sngeth.com/zig/systems-programming/breaking-changes/2025/10/24/zig-0-15-migration-roadblocks/)
-
-major breaking release with i/o overhaul ("writergate") and build system changes.
+[release notes](https://ziglang.org/download/0.15.1/release-notes.html)
 
 ## notes
 
-- [arraylist](./arraylist.md) - now requires allocator on every method call
-- [io](./io.md) - new reader/writer interfaces with explicit buffers
-- [build](./build.md) - module imports pattern with `createModule`
-- [comptime](./comptime.md) - type-returning functions, inline for, reflection
-- [concurrency](./concurrency.md) - thread pools, mutexes, atomics, backoff
+- [arraylist](./arraylist.md) - ownership patterns (toOwnedSlice vs deinit)
+- [io](./io.md) - explicit buffers, http client/server, tls quirk
+- [build](./build.md) - createModule + imports, hash trick
+- [comptime](./comptime.md) - type generation, tuple synthesis, validation
+- [concurrency](./concurrency.md) - atomics vs mutex, callback pattern

languages/ziglang/0.15/arraylist.md

···
 # arraylist
 
-in 0.15, `std.ArrayList` became "unmanaged" by default - it no longer stores the allocator internally. you pass the allocator to every method call.
-
-## why this changed
-
-the [release notes](https://ziglang.org/download/0.15.1/release-notes.html) explain the reasoning: "having an extra field is more complicated than not having an extra field, so not having it is the null hypothesis."
-
-storing the allocator had downsides:
-- worse method signatures when dealing with capacity reservations
-- can't statically initialize (no allocator available at comptime)
-- extra memory cost, especially for nested containers (arraylist of arraylists)
+0.15 made arraylist unmanaged - allocator passed to each method. the compiler catches missing allocators immediately, so that's not worth documenting. what matters is ownership.
 
-the supposed upside - "avoiding accidentally using the wrong allocator" - isn't worth it since the correct allocator is always nearby and misuse can be safety-checked.
+## ownership patterns
 
-## the pattern
+**build and discard** - most common. defer cleanup, use `.items` to borrow:
 
 ```zig
-var buf: std.ArrayList(u8) = .{};
+var buf: std.ArrayList(u8) = .empty;
 defer buf.deinit(alloc);
 
-try buf.append(alloc, 'x');
-try buf.appendSlice(alloc, "hello");
-
-const w = buf.writer(alloc);
-try w.print("{d}", .{42});
+try buf.print(alloc, "{s}: {d}", .{ name, value });
+sendResponse(buf.items);  // borrow the slice
 ```
 
-every mutating method takes allocator as the first argument. this is the part i keep forgetting - `append(alloc, item)` not `append(item)`.
-
-## initialization
-
-you can now statically initialize because there's no allocator field:
+**build and return** - transfer ownership, no defer:
 
 ```zig
-var buf: std.ArrayList(u8) = .{};  // zero-init, no allocator needed yet
+var buf: std.ArrayList(u8) = .empty;
+// no defer - caller owns the memory
+
+try buf.appendSlice(alloc, data);
+return buf.toOwnedSlice(alloc);
 ```
 
-vs the old managed pattern which required an allocator upfront.
+the difference: `.items` borrows (arraylist still owns the memory), `.toOwnedSlice()` transfers (caller must free).
 
-## writer
+see: [dashboard.zig#L187](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/dashboard.zig#L187) for the return pattern
 
-the writer also needs the allocator:
+## direct methods vs writer
+
+arraylist has `.print()` directly - you don't always need a writer:
 
 ```zig
-const w = buf.writer(alloc);
-try w.writeAll("data");
-try w.print("{s}: {d}", .{ name, value });
+try buf.print(alloc, "{{\"count\":{d}}}", .{count});
 ```
 
-see: [leaflet-search/backend/src/server.zig#L129](https://tangled.sh/@zzstoatzz.io/leaflet-search/tree/main/backend/src/server.zig#L129)
-
-## managed still exists
-
-if you really want the old behavior:
+use `.writer(alloc)` when you need to pass to something expecting `std.Io.Writer`:
 
 ```zig
-var buf = std.array_list.Managed(u8).init(alloc);
-defer buf.deinit();
-
-try buf.append('x');  // no allocator argument
+const w = buf.writer(alloc);
+try json.stringify(value, .{}, w);
 ```
 
-but this is marked for eventual removal. get used to passing the allocator.
+## why unmanaged
+
+from the [release notes](https://ziglang.org/download/0.15.1/release-notes.html): storing the allocator had costs - worse method signatures for reservations, can't statically initialize, extra memory for nested containers. the benefits (convenience, avoiding wrong allocator) didn't justify it since the allocator is always nearby.

languages/ziglang/0.15/build.md

···
-# build system
+# build
 
-0.15 changed how you declare module dependencies in build.zig. the new pattern uses `createModule` with an `imports` array.
+## 0.15 change
 
-## executable with dependencies
+pre-0.15 used `exe.addModule()`. now use `createModule` with `imports` array:
 
 ```zig
-const websocket = b.dependency("websocket", .{
-    .target = target,
-    .optimize = optimize,
-});
-
 const exe = b.addExecutable(.{
     .name = "myapp",
     .root_module = b.createModule(.{
···
 });
 ```
 
-the key difference from pre-0.15:
-- use `root_module` with `createModule()` instead of just `root_source_file`
-- dependencies go in the `imports` array, not via `addModule()` calls
-
-see: [music-atmosphere-feed/build.zig](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/build.zig)
-
-## library module
-
-for a library that exposes a module to consumers:
+## dependency hash trick
 
-```zig
-const mod = b.addModule("zql", .{
-    .root_source_file = b.path("src/root.zig"),
-    .target = target,
-    .optimize = optimize,
-});
+to get the hash for build.zig.zon, run `zig build` with a wrong hash. it tells you the correct one:
 
-const tests = b.addTest(.{ .root_module = mod });
 ```
-
-the module name ("zql") is what consumers use in their `imports` array.
-
-see: [zql/build.zig](https://tangled.sh/@zzstoatzz.io/zql/tree/main/build.zig)
-
-## build.zig.zon
-
-dependencies are declared in build.zig.zon:
-
-```zig
-.{
-    .name = .my_project,
-    .version = "0.0.1",
-    .minimum_zig_version = "0.15.0",
-    .dependencies = .{
-        .websocket = .{
-            .url = "https://github.com/karlseguin/websocket.zig/archive/refs/heads/master.tar.gz",
-            .hash = "...",
-        },
-    },
-}
-```
-
-to get the hash, run `zig build` with a wrong hash - it'll tell you the correct one.
-
-## linking system libraries
-
-for sqlite, link both libc and the system library:
-
-```zig
-exe.linkLibC();
-exe.linkSystemLibrary("sqlite3");
+error: hash mismatch... expected 1220abc..., found 1220def...
 ```
 
-see: [music-atmosphere-feed/build.zig#L30-31](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/build.zig#L30)
-
-## run step
-
-```zig
-const run_cmd = b.addRunArtifact(exe);
-run_cmd.step.dependOn(b.getInstallStep());
-
-if (b.args) |args| {
-    run_cmd.addArgs(args);
-}
-
-const run_step = b.step("run", "Run the server");
-run_step.dependOn(&run_cmd.step);
-```
+## don't forget
 
-this lets you do `zig build run -- --port 8080`.
+`b.installArtifact(exe)` - without this, `zig build` produces nothing.

languages/ziglang/0.15/comptime.md

···
 # comptime
 
-zig's comptime is where it gets interesting. you can generate types, validate inputs, and unroll loops at compile time.
+comptime lets you generate types, validate inputs, and catch errors at compile time. for a complete example, see [zql](https://tangled.sh/@zzstoatzz.io/zql) which parses SQL at comptime and generates type-safe bindings.
 
 ## type-returning functions
 
-the pattern: a function that takes comptime parameters and returns a `type`. the returned type is a struct with fields and methods derived from the input.
+a function that takes comptime params and returns a `type`:
 
 ```zig
-pub fn Query(comptime sql: []const u8) type {
-    comptime {
-        const parsed = parser.parse(sql);
-        return struct {
-            pub const raw = sql;
-            pub const params: []const []const u8 = parsed.params[0..parsed.params_len];
-            pub const columns: []const []const u8 = parsed.columns[0..parsed.columns_len];
+pub fn Wrapper(comptime T: type) type {
+    return struct {
+        value: T,
 
-            pub fn bind(args: anytype) BindTuple(@TypeOf(args)) {
-                // ...
-            }
-        };
-    }
+        pub fn get(self: @This()) T {
+            return self.value;
+        }
+    };
 }
 ```
 
-usage:
-
-```zig
-const Q = Query("SELECT id, name FROM users WHERE age > :min_age");
-// Q.params = ["min_age"]
-// Q.columns = ["id", "name"]
-```
+`@This()` refers to the struct being defined - necessary since the struct is anonymous.
 
-the entire SQL is parsed at compile time. no runtime overhead, and typos in parameter names are compile errors.
+## generating tuple types from struct fields
 
-see: [zql/src/Query.zig](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/Query.zig)
+extract field types in a specific order to build a tuple:
 
-## inline for
+```zig
+fn BindTuple(comptime Args: type, comptime param_names: []const []const u8) type {
+    const fields = @typeInfo(Args).@"struct".fields;
+    var types: [param_names.len]type = undefined;
 
-`inline for` unrolls the loop at compile time. each iteration becomes separate code:
-
-```zig
-inline for (params) |p| {
-    if (!hasField(fields, p)) {
-        @compileError("missing param :" ++ p);
+    inline for (param_names, 0..) |name, i| {
+        for (fields) |f| {
+            if (std.mem.eql(u8, f.name, name)) {
+                types[i] = f.type;
+                break;
+            }
+        }
     }
+    return std.meta.Tuple(&types);
 }
 ```
 
-this checks at compile time that your args struct has all required SQL parameters. missing one? compile error with the exact parameter name.
-
-see: [zql/src/Query.zig#L23](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/Query.zig#L23)
+this reorders struct fields into a tuple matching the parameter order. useful for binding named args to positional parameters.
 
-## reflection
-
-access struct fields at comptime with `@typeInfo`:
-
-```zig
-const fields = @typeInfo(Args).@"struct".fields;
-inline for (fields) |f| {
-    @field(result, f.name) = @field(args, f.name);
-}
-```
-
-note the `@"struct"` syntax - struct is a keyword, so it needs quoting.
-
-this pattern maps an arbitrary struct's fields to another structure, checking types and names at compile time.
-
-see: [zql/src/Query.zig#L55](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/Query.zig#L55)
+see: [zql/src/Query.zig#L78](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/Query.zig#L78)
 
 ## compile-time validation
 
 `@compileError` stops compilation with a message:
 
 ```zig
-if (!hasColumn(f.name)) {
-    @compileError("struct field '" ++ f.name ++ "' not found in query columns");
+inline for (required_fields) |name| {
+    if (!hasField(T, name)) {
+        @compileError("missing required field: " ++ name);
+    }
 }
 ```
 
-this is how you make invalid states unrepresentable - if your code compiles, your query parameters match your struct fields.
+if your code compiles, it's valid. invalid states are unrepresentable.
 
 ## branch quota
 
-complex comptime parsing can hit the default branch quota (1000 backwards branches). increase it:
+complex comptime parsing hits the default branch quota (1000 backwards branches). scale it with input:
 
 ```zig
-@setEvalBranchQuota(sql.len * 100);
+@setEvalBranchQuota(input.len * 100);
 ```
 
-put this at the start of your comptime block. without it, complex SQL parsing fails with "evaluation exceeded maximum branch quota."
+without this, complex parsing fails with "evaluation exceeded maximum branch quota."
 
 see: [zql/src/parse.zig#L48](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/parse.zig#L48)
 
-## why this matters
-
-the zql library parses SQL at compile time and generates type-safe bindings:
-
-```zig
-const Q = Query("INSERT INTO users (name, age) VALUES (:name, :age)");
+## constraints
 
-// this is checked at compile time:
-const args = Q.bind(.{ .name = "alice", .age = 25 });
-// args is a tuple: ("alice", 25) in parameter order
-
-// if you typo .nme instead of .name, compile error
-```
-
-no runtime SQL parsing, no string concatenation, no injection vulnerabilities (because the SQL is a comptime string literal).
+- no allocation at comptime - use fixed-size arrays
+- no runtime values - everything must be known at compile time
+- comptime code runs during compilation, adding build time

languages/ziglang/0.15/concurrency.md

···
 # concurrency
 
-zig's concurrency primitives are in `std.Thread`. no async/await - just threads, mutexes, and atomics.
+zig has threads, mutexes, and atomics. no async/await. for syntax, see std.Thread docs. these notes cover design decisions.
 
-## thread pool
+## when to use atomics vs mutex
 
-for handling concurrent connections without spawning unbounded threads:
+**atomics for simple counters:**
 
 ```zig
-var pool: Thread.Pool = undefined;
-try pool.init(.{
-    .allocator = allocator,
-    .n_jobs = 16,
-});
-defer pool.deinit();
+posts_checked: std.atomic.Value(u64) = .init(0),
 
-// in accept loop:
-pool.spawn(handleConnection, .{conn}) catch |err| {
-    conn.stream.close();  // cleanup on spawn failure
-};
+_ = self.posts_checked.fetchAdd(1, .monotonic);
 ```
 
-the pool maintains a fixed number of worker threads. `spawn` queues work; if the pool is busy, it blocks or fails depending on configuration.
-
-see: [music-atmosphere-feed/src/main.zig#L29](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/main.zig#L29)
-
-## background threads
-
-for long-running tasks like stream consumers:
+**mutex for complex data structures:**
 
 ```zig
-const thread = try Thread.spawn(.{}, consumer, .{allocator});
-defer thread.join();  // wait for completion on shutdown
+bufo_matches: std.StringHashMap(MatchInfo),
+bufo_mutex: Thread.Mutex = .{},
+
+self.bufo_mutex.lock();
+defer self.bufo_mutex.unlock();
+try self.bufo_matches.put(name, info);
 ```
 
-the third argument is a tuple of arguments passed to the function. `join()` blocks until the thread exits.
+the pattern in [find-bufo/bot/src/stats.zig](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/stats.zig): atomics for the five simple counters (posts_checked, matches_found, etc.), mutex for the hashmap of per-bufo match data.
 
-see: [music-atmosphere-feed/src/main.zig#L25](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/main.zig#L25)
+rule: if it's a single integer, use atomic. if it's a container or multi-field update, use mutex.
 
-## mutex
+## memory ordering
 
-for protecting shared state:
+all usages in these projects use `.monotonic` - sufficient for independent counters where you just need eventual visibility, not synchronization between threads.
 
-```zig
-const State = struct {
-    mutex: Thread.Mutex = .{},
-    data: SomeData,
-};
+use stricter orderings (`.acquire`, `.release`) when one thread's write must be visible to another thread before proceeding. none of these projects need that.
 
-state.mutex.lock();
-defer state.mutex.unlock();
-// critical section - only one thread at a time
-```
+## callback pattern
 
-always use `defer` for unlock. if you return early or error, the mutex still unlocks.
-
-see: [find-bufo/bot/src/main.zig#L102](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/main.zig#L102)
-
-## atomics
-
-for lock-free counters and flags:
+jetstream doesn't use channels or message passing. it takes a function pointer:
 
 ```zig
-const Stats = struct {
-    messages: std.atomic.Value(u64) = .init(0),
-};
+callback: *const fn (Post) void,
 
-// increment (returns previous value)
-_ = self.messages.fetchAdd(1, .monotonic);
-
-// read
-const count = self.messages.load(.monotonic);
-
-// write
-self.messages.store(42, .monotonic);
+self.callback(.{
+    .uri = uri,
+    .text = text,
+});
 ```
 
-`.monotonic` is the memory ordering - sufficient for simple counters. use stricter orderings (`.acquire`, `.release`, `.seq_cst`) when you need synchronization guarantees between threads.
+simpler than channels when you just need to notify one consumer.
 
-see: [music-atmosphere-feed/src/stats.zig#L12](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/stats.zig#L12)
+see: [find-bufo/bot/src/jetstream.zig#L18](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/jetstream.zig#L18)
 
-## exponential backoff
+## reconnection
 
-for reconnection loops that don't hammer servers:
+exponential backoff for network consumers:
 
 ```zig
 var backoff: u64 = 1;
 const max_backoff: u64 = 60;
 
 while (true) {
-    connect() catch |err| {
-        std.debug.print("error: {}, retry in {}s\n", .{ err, backoff });
-    };
+    connect() catch {};
     posix.nanosleep(backoff, 0);
     backoff = @min(backoff * 2, max_backoff);
 }
 ```
 
-starts at 1 second, doubles each failure, caps at 60 seconds. simple and effective.
-
-see: [music-atmosphere-feed/src/jetstream.zig#L22](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/jetstream.zig#L22)
-
-## no async
-
-zig removed async/await. the reasoning: it added complexity without clear benefits over threads for most use cases. if you need high concurrency, use a thread pool or io_uring (linux) / kqueue (macos).
-
-for bluesky bots and feed generators, a thread pool with 16 workers handles thousands of concurrent connections fine.
+starts at 1s, doubles each failure, caps at 60s.

languages/ziglang/0.15/io.md

···
-# i/o interfaces
-
-0.15 completely rewrote `std.io.Reader` and `std.io.Writer`. this was called "writergate" (referencing the earlier "allocgate" breaking change). the [release notes](https://ziglang.org/download/0.15.1/release-notes.html) acknowledge it as "extremely breaking" but necessary.
-
-## what changed
-
-the old interfaces were generic (`anytype`), which forced every function that touched a reader/writer to also be generic. this "poisoned" APIs throughout codebases.
+# i/o
 
-the new interfaces are concrete types with explicit buffers. the buffer is part of the interface, not the implementation.
+0.15 replaced generic `anytype` reader/writer with concrete types using explicit buffers. see [release notes](https://ziglang.org/download/0.15.1/release-notes.html) for the rationale.
 
-## the pattern
-
-you now create explicit buffers and pass them to readers/writers:
+## http server pattern
 
 ```zig
 var read_buffer: [8192]u8 = undefined;
···
 var server = http.Server.init(reader.interface(), &writer.interface);
 ```
 
-notice:
-- buffers are stack-allocated arrays you own
-- `.interface()` extracts the concrete interface type
-- http.Server no longer depends on `std.net` - it just takes interfaces
+the buffers are yours - stack allocated, explicit size. `.interface()` extracts the concrete type that http.Server expects.
 
-see: [music-atmosphere-feed/src/http.zig#L14-21](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/http.zig#L14)
+see: [http.zig#L14](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/http.zig#L14)
 
-## why this matters
+## http client pattern
 
-before 0.15, if you wrote a function that accepted a writer, you'd write:
-
-```zig
-fn writeStuff(writer: anytype) !void { ... }
-```
-
-now you write:
-
-```zig
-fn writeStuff(writer: *std.Io.Writer) !void { ... }
-```
-
-concrete types mean better error messages, actual type checking, and no generic explosion through your codebase.
-
-## flushing
-
-with buffered i/o, you need to flush explicitly. the buffer accumulates writes and only sends when full or flushed:
+for api calls, use `Io.Writer.Allocating` to collect the response:
 
 ```zig
-try writer.print("hello", .{});
-try writer.flush();  // actually sends
-```
-
-forgetting to flush is a common bug - data sits in the buffer forever.
-
-## allocating writer
-
-for dynamic output (like building json responses), use an allocating writer:
+var client = http.Client{ .allocator = allocator };
+defer client.deinit();
 
-```zig
 var aw: std.Io.Writer.Allocating = .init(allocator);
 defer aw.deinit();
 
 const result = client.fetch(.{
+    .location = .{ .url = url },
     .response_writer = &aw.writer,
-    ...
-});
+}) catch |err| return err;
+
+if (result.status != .ok) return error.FetchFailed;
 
 const response = aw.toArrayList().items;
 ```
 
-see: [find-bufo/bot/src/main.zig#L202-220](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/main.zig#L202)
-
-## fixed writer
-
-for writing into a fixed-size buffer:
-
-```zig
-var buf: [256]u8 = undefined;
-var w: std.Io.Writer = .fixed(&buf);
-try w.print("{s}: {d}", .{ name, value });
-```
+see: [find-bufo/bot/src/main.zig#L196](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/main.zig#L196)
 
 ## tls reading quirk
 
-when reading from tls streams, you must loop until data arrives. a return of 0 doesn't mean EOF - it means "try again":
+when reading from raw tls (not http.Client), you must loop until data arrives. `n == 0` means "try again", not EOF:
 
 ```zig
 outer: while (total_read < response_buf.len) {
···
             total_read += n;
             break;
         }
-        // n == 0 means keep trying, not EOF
+        // n == 0: tls may have consumed input without producing output
+        // (buffering partial records, renegotiation, etc.)
     }
 }
 ```
 
-this pattern comes from [websocket.zig](https://github.com/karlseguin/websocket.zig). without the inner loop, you'll read 0 bytes and think you're done.
+this happens because tls decryption can consume input bytes without producing output yet. the inner loop keeps trying until actual data appears.
+
+also: raw tls needs explicit flush at both layers:
+```zig
+tls_client.writer.flush() catch return error.Failed;
+stream_writer.interface.flush() catch return error.Failed;
+```
+
+see: [atproto.zig#L285](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/atproto.zig#L285)
+
+## when you don't need to flush
+
+high-level apis (http.Server, http.Client) handle flushing internally. `request.respond()` flushes for you. only raw tls/stream code needs explicit flushes.