split 0.15 notes into topic files

- arraylist.md: why allocator is now passed to every method
- io.md: writergate, explicit buffers, tls reading quirk
- build.md: createModule pattern, build.zig.zon
- comptime.md: type-returning functions, inline for, reflection
- concurrency.md: thread pools, mutexes, atomics, backoff

README is now just an index with links

🤖 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
 
-patterns from zig 0.15+ development. the 0.15 release was a [major breaking change](https://ziglang.org/download/0.15.1/release-notes.html) with a complete i/o overhaul.
-
-## contents
-
-- [build system](#build-system) - module imports, dependencies
-- [memory](#memory) - allocators, arenas, lifecycle
-- [error handling](#error-handling) - try, catch, labeled blocks
-- [concurrency](#concurrency) - threads, pools, atomics, backoff
-- [http server](#http-server) - new reader/writer interfaces
-- [websockets](#websockets) - tls client pattern
-- [json](#json) - parsing and formatting
-- [comptime](#comptime) - type-returning functions, reflection
-- [strings](#strings) - splitting, searching, encoding
-
----
-
-## build system
-
-### executable with dependencies
-
-the 0.15 pattern uses `createModule` with an `imports` array instead of `addModule`:
-
-```zig
-const exe = b.addExecutable(.{
-    .name = "myapp",
-    .root_module = b.createModule(.{
-        .root_source_file = b.path("src/main.zig"),
-        .target = target,
-        .optimize = optimize,
-        .imports = &.{
-            .{ .name = "websocket", .module = websocket.module("websocket") },
-            .{ .name = "zqlite", .module = zqlite.module("zqlite") },
-        },
-    }),
-});
-```
+[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/)
 
-see: [music-atmosphere-feed/build.zig](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/build.zig)
+major breaking release with i/o overhaul ("writergate") and build system changes.
 
-### library module
+## notes
 
-for libraries that expose a module to consumers:
-
-```zig
-const mod = b.addModule("zql", .{
-    .root_source_file = b.path("src/root.zig"),
-    .target = target,
-    .optimize = optimize,
-});
-
-const tests = b.addTest(.{ .root_module = mod });
-```
-
-see: [zql/build.zig](https://tangled.sh/@zzstoatzz.io/zql/tree/main/build.zig)
-
-### build.zig.zon
-
-dependency declaration format:
-
-```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 = "...",
-        },
-    },
-}
-```
-
----
-
-## memory
-
-### general purpose allocator
-
-use for application-lifetime allocations. check for leaks on deinit:
-
-```zig
-var gpa = std.heap.GeneralPurposeAllocator(.{}){};
-defer _ = gpa.deinit();
-const allocator = gpa.allocator();
-```
-
-see: [music-atmosphere-feed/src/main.zig:14-16](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/main.zig#L14)
-
-### arena allocator
-
-use for request-scoped memory where everything can be freed at once:
-
-```zig
-var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
-defer arena.deinit();
-const alloc = arena.allocator();
-// all allocations freed when arena deinits
-```
-
-this pattern appears throughout http handlers where we need temporary allocations for building responses:
-
-see: [leaflet-search/backend/src/server.zig:65-67](https://tangled.sh/@zzstoatzz.io/leaflet-search/tree/main/backend/src/server.zig#L65)
-
-### arraylist
-
-0.15 changed arraylist to require allocator on each method call:
-
-```zig
-var buf: std.ArrayList(u8) = .{};
-defer buf.deinit(alloc);
-const w = buf.writer(alloc);
-try w.writeAll("data");
-```
-
-see: [leaflet-search/backend/src/server.zig:129-132](https://tangled.sh/@zzstoatzz.io/leaflet-search/tree/main/backend/src/server.zig#L129)
-
----
-
-## error handling
-
-### try (propagation)
-
-most common pattern - propagate errors to caller:
-
-```zig
-const result = try doSomething();
-```
-
-### catch with specific handling
-
-handle specific errors differently:
-
-```zig
-const n = tls_client.reader.stream(&w, .limited(len)) catch |err| {
-    if (err == error.EndOfStream) break :outer;
-    return error.Failed;
-};
-```
-
-### catch with default
-
-provide fallback value:
-
-```zig
-const port = std.fmt.parseInt(u16, port_str, 10) catch 3000;
-const host = std.posix.getenv("HOST") orelse "localhost";
-```
-
-see: [music-atmosphere-feed/src/main.zig:37-40](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/main.zig#L37)
-
-### labeled blocks for complex fallbacks
-
-when you need multi-step fallback logic:
-
-```zig
-const port: u16 = blk: {
-    const port_str = posix.getenv("PORT") orelse "3000";
-    break :blk std.fmt.parseInt(u16, port_str, 10) catch 3000;
-};
-```
-
-see: [music-atmosphere-feed/src/main.zig:37-40](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/main.zig#L37)
-
-### defer / errdefer
-
-cleanup resources on scope exit:
-
-```zig
-const resource = try allocate();
-errdefer deallocate(resource);  // only runs if error after this point
-defer deallocate(resource);     // always runs
-```
-
----
-
-## concurrency
-
-### thread pool
-
-for handling concurrent http connections:
-
-```zig
-var pool: Thread.Pool = undefined;
-try pool.init(.{ .allocator = allocator, .n_jobs = 16 });
-defer pool.deinit();
-
-pool.spawn(handleConnection, .{conn}) catch |err| {
-    conn.stream.close();
-};
-```
-
-see: [music-atmosphere-feed/src/main.zig:29-34](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/main.zig#L29)
-
-### background thread
-
-for long-running tasks like stream consumers:
-
-```zig
-const thread = try Thread.spawn(.{}, consumer, .{allocator});
-defer thread.join();
-```
-
-see: [music-atmosphere-feed/src/main.zig:25-26](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/main.zig#L25)
-
-### mutex
-
-for protecting shared state across threads:
-
-```zig
-const BotState = struct {
-    mutex: Thread.Mutex = .{},
-    // ... other fields
-};
-
-state.mutex.lock();
-defer state.mutex.unlock();
-// critical section
-```
-
-see: [find-bufo/bot/src/main.zig:21](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/main.zig#L21), [find-bufo/bot/src/main.zig:102-103](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/main.zig#L102)
-
-### atomic values
-
-for lock-free counters and flags:
-
-```zig
-messages: std.atomic.Value(u64) = .init(0),
-
-// increment
-_ = self.messages.fetchAdd(1, .monotonic);
-
-// read
-const count = self.messages.load(.monotonic);
-```
-
-see: [music-atmosphere-feed/src/stats.zig:12](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/stats.zig#L12)
-
-### exponential backoff
-
-for reconnection loops:
-
-```zig
-var backoff: u64 = 1;
-const max_backoff: u64 = 60;
-
-while (true) {
-    connect() catch {};
-    posix.nanosleep(backoff, 0);
-    backoff = @min(backoff * 2, max_backoff);
-}
-```
-
-see: [music-atmosphere-feed/src/jetstream.zig:22-31](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/jetstream.zig#L22)
-
----
-
-## http server
-
-0.15 completely rewrote i/o interfaces. the new pattern uses explicit buffers:
-
-```zig
-var read_buffer: [8192]u8 = undefined;
-var write_buffer: [8192]u8 = undefined;
-
-var reader = conn.stream.reader(&read_buffer);
-var writer = conn.stream.writer(&write_buffer);
-
-var server = http.Server.init(reader.interface(), &writer.interface);
-
-while (true) {
-    var request = server.receiveHead() catch return;
-    handleRequest(&request) catch return;
-    if (!request.head.keep_alive) return;
-}
-```
-
-see: [music-atmosphere-feed/src/http.zig:12-36](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/http.zig#L12)
-
-### responding
-
-```zig
-try request.respond(body, .{
-    .status = .ok,
-    .extra_headers = &.{
-        .{ .name = "content-type", .value = "application/json" },
-    },
-});
-```
-
-see: [leaflet-search/backend/src/server.zig:137-147](https://tangled.sh/@zzstoatzz.io/leaflet-search/tree/main/backend/src/server.zig#L137)
-
-### socket timeouts
-
-```zig
-const timeout = std.mem.toBytes(posix.timeval{ .sec = 30, .usec = 0 });
-try posix.setsockopt(fd, posix.SOL.SOCKET, posix.SO.RCVTIMEO, &timeout);
-try posix.setsockopt(fd, posix.SOL.SOCKET, posix.SO.SNDTIMEO, &timeout);
-```
-
-see: [music-atmosphere-feed/src/main.zig:65-71](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/main.zig#L65)
-
----
-
-## websockets
-
-using [websocket.zig](https://github.com/karlseguin/websocket.zig) for tls websocket connections:
-
-```zig
-var client = websocket.Client.init(allocator, .{
-    .host = host,
-    .port = 443,
-    .tls = true,
-    .max_size = 1024 * 1024,
-}) catch return err;
-defer client.deinit();
-
-client.handshake(path, .{ .headers = host_header }) catch return err;
-
-var handler = Handler{ .allocator = allocator };
-client.readLoop(&handler) catch return err;
-```
-
-the handler struct implements `serverMessage` and `close`:
-
-```zig
-const Handler = struct {
-    allocator: Allocator,
-
-    pub fn serverMessage(self: *Handler, data: []const u8) !void {
-        // process message
-    }
-
-    pub fn close(_: *Handler) void {
-        std.debug.print("connection closed\n", .{});
-    }
-};
-```
-
-see: [music-atmosphere-feed/src/jetstream.zig:40-66](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/jetstream.zig#L40)
-
----
-
-## json
-
-### parsing
-
-```zig
-const parsed = json.parseFromSlice(json.Value, allocator, data, .{}) catch return;
-defer parsed.deinit();
-
-const root = parsed.value.object;
-const val = root.get("key") orelse return;
-if (val != .string) return;
-const s = val.string;
-```
-
-see: [find-bufo/bot/src/jetstream.zig:95-98](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/jetstream.zig#L95)
-
-### type checking pattern
-
-common pattern for safely extracting nested json:
-
-```zig
-const kind = root.get("kind") orelse return error.NotAPost;
-if (kind != .string or !mem.eql(u8, kind.string, "commit")) return error.NotAPost;
-
-const commit = root.get("commit") orelse return error.NotAPost;
-if (commit != .object) return error.NotAPost;
-```
-
-see: [music-atmosphere-feed/src/jetstream.zig:99-109](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/jetstream.zig#L99)
-
----
-
-## comptime
-
-### type-returning functions
-
-create types at compile time based on input:
-
-```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 validateArgs(comptime Args: type) void {
-                // compile-time validation
-            }
-        };
-    }
-}
-```
-
-see: [zql/src/Query.zig:10-108](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/Query.zig#L10)
-
-### inline for
-
-loop unrolled at compile time:
-
-```zig
-inline for (params) |p| {
-    if (!hasField(fields, p)) {
-        @compileError("missing param :" ++ p);
-    }
-}
-```
-
-see: [zql/src/Query.zig:23-27](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/Query.zig#L23)
-
-### reflection
-
-access struct fields at comptime:
-
-```zig
-const fields = @typeInfo(Args).@"struct".fields;
-inline for (fields) |f| {
-    @field(result, f.name) = @field(args, f.name);
-}
-```
-
-see: [zql/src/Query.zig:55-64](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/Query.zig#L55)
-
-### branch quota
-
-for complex comptime parsing, increase the default branch quota:
-
-```zig
-@setEvalBranchQuota(sql.len * 100);
-```
-
-see: [zql/src/parse.zig:48](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/parse.zig#L48)
-
----
-
-## strings
-
-### splitting
-
-```zig
-var parts = mem.splitScalar(u8, data, '/');
-const first = parts.next() orelse return error.Invalid;
-```
-
-### prefix/suffix checks
-
-```zig
-if (mem.startsWith(u8, target, "/api/")) { }
-if (mem.endsWith(u8, id, ".gif")) { }
-```
-
-see: [find-bufo/bot/src/main.zig:142](https://tangled.sh/@zzstoatzz.io/find-bufo/tree/main/bot/src/main.zig#L142)
-
-### searching
-
-```zig
-if (mem.indexOf(u8, response, "\r\n\r\n")) |idx| {
-    const body = response[idx + 4 ..];
-}
-```
-
-### url decoding
-
-```zig
-const buf = try alloc.dupe(u8, encoded);
-const decoded = std.Uri.percentDecodeInPlace(buf);
-```
-
-see: [leaflet-search/backend/src/server.zig:115-116](https://tangled.sh/@zzstoatzz.io/leaflet-search/tree/main/backend/src/server.zig#L115)
-
-### multi-line strings
-
-```zig
-const sql =
-    \\CREATE TABLE IF NOT EXISTS posts (
-    \\  uri TEXT PRIMARY KEY,
-    \\  cid TEXT NOT NULL
-    \\)
-;
-```
+- [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

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)
+
+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.
+
+## the pattern
+
+```zig
+var buf: std.ArrayList(u8) = .{};
+defer buf.deinit(alloc);
+
+try buf.append(alloc, 'x');
+try buf.appendSlice(alloc, "hello");
+
+const w = buf.writer(alloc);
+try w.print("{d}", .{42});
+```
+
+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:
+
+```zig
+var buf: std.ArrayList(u8) = .{};  // zero-init, no allocator needed yet
+```
+
+vs the old managed pattern which required an allocator upfront.
+
+## writer
+
+the writer also needs the allocator:
+
+```zig
+const w = buf.writer(alloc);
+try w.writeAll("data");
+try w.print("{s}: {d}", .{ name, value });
+```
+
+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:
+
+```zig
+var buf = std.array_list.Managed(u8).init(alloc);
+defer buf.deinit();
+
+try buf.append('x');  // no allocator argument
+```
+
+but this is marked for eventual removal. get used to passing the allocator.

languages/ziglang/0.15/build.md

···
+# build system
+
+0.15 changed how you declare module dependencies in build.zig. the new pattern uses `createModule` with an `imports` array.
+
+## executable with dependencies
+
+```zig
+const websocket = b.dependency("websocket", .{
+    .target = target,
+    .optimize = optimize,
+});
+
+const exe = b.addExecutable(.{
+    .name = "myapp",
+    .root_module = b.createModule(.{
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+        .imports = &.{
+            .{ .name = "websocket", .module = websocket.module("websocket") },
+        },
+    }),
+});
+```
+
+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:
+
+```zig
+const mod = b.addModule("zql", .{
+    .root_source_file = b.path("src/root.zig"),
+    .target = target,
+    .optimize = optimize,
+});
+
+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");
+```
+
+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);
+```
+
+this lets you do `zig build run -- --port 8080`.

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.
+
+## 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.
+
+```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 bind(args: anytype) BindTuple(@TypeOf(args)) {
+                // ...
+            }
+        };
+    }
+}
+```
+
+usage:
+
+```zig
+const Q = Query("SELECT id, name FROM users WHERE age > :min_age");
+// Q.params = ["min_age"]
+// Q.columns = ["id", "name"]
+```
+
+the entire SQL is parsed at compile time. no runtime overhead, and typos in parameter names are compile errors.
+
+see: [zql/src/Query.zig](https://tangled.sh/@zzstoatzz.io/zql/tree/main/src/Query.zig)
+
+## inline for
+
+`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);
+    }
+}
+```
+
+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)
+
+## 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)
+
+## compile-time validation
+
+`@compileError` stops compilation with a message:
+
+```zig
+if (!hasColumn(f.name)) {
+    @compileError("struct field '" ++ f.name ++ "' not found in query columns");
+}
+```
+
+this is how you make invalid states unrepresentable - if your code compiles, your query parameters match your struct fields.
+
+## branch quota
+
+complex comptime parsing can hit the default branch quota (1000 backwards branches). increase it:
+
+```zig
+@setEvalBranchQuota(sql.len * 100);
+```
+
+put this at the start of your comptime block. without it, complex SQL 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)");
+
+// 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).

languages/ziglang/0.15/concurrency.md

···
+# concurrency
+
+zig's concurrency primitives are in `std.Thread`. no async/await - just threads, mutexes, and atomics.
+
+## thread pool
+
+for handling concurrent connections without spawning unbounded threads:
+
+```zig
+var pool: Thread.Pool = undefined;
+try pool.init(.{
+    .allocator = allocator,
+    .n_jobs = 16,
+});
+defer pool.deinit();
+
+// in accept loop:
+pool.spawn(handleConnection, .{conn}) catch |err| {
+    conn.stream.close();  // cleanup on spawn failure
+};
+```
+
+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:
+
+```zig
+const thread = try Thread.spawn(.{}, consumer, .{allocator});
+defer thread.join();  // wait for completion on shutdown
+```
+
+the third argument is a tuple of arguments passed to the function. `join()` blocks until the thread exits.
+
+see: [music-atmosphere-feed/src/main.zig#L25](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/main.zig#L25)
+
+## mutex
+
+for protecting shared state:
+
+```zig
+const State = struct {
+    mutex: Thread.Mutex = .{},
+    data: SomeData,
+};
+
+state.mutex.lock();
+defer state.mutex.unlock();
+// critical section - only one thread at a time
+```
+
+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:
+
+```zig
+const Stats = struct {
+    messages: std.atomic.Value(u64) = .init(0),
+};
+
+// increment (returns previous value)
+_ = self.messages.fetchAdd(1, .monotonic);
+
+// read
+const count = self.messages.load(.monotonic);
+
+// write
+self.messages.store(42, .monotonic);
+```
+
+`.monotonic` is the memory ordering - sufficient for simple counters. use stricter orderings (`.acquire`, `.release`, `.seq_cst`) when you need synchronization guarantees between threads.
+
+see: [music-atmosphere-feed/src/stats.zig#L12](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/stats.zig#L12)
+
+## exponential backoff
+
+for reconnection loops that don't hammer servers:
+
+```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 });
+    };
+    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.

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.
+
+the new interfaces are concrete types with explicit buffers. the buffer is part of the interface, not the implementation.
+
+## the pattern
+
+you now create explicit buffers and pass them to readers/writers:
+
+```zig
+var read_buffer: [8192]u8 = undefined;
+var write_buffer: [8192]u8 = undefined;
+
+var reader = conn.stream.reader(&read_buffer);
+var writer = conn.stream.writer(&write_buffer);
+
+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
+
+see: [music-atmosphere-feed/src/http.zig#L14-21](https://tangled.sh/@zzstoatzz.io/music-atmosphere-feed/tree/main/src/http.zig#L14)
+
+## why this matters
+
+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:
+
+```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:
+
+```zig
+var aw: std.Io.Writer.Allocating = .init(allocator);
+defer aw.deinit();
+
+const result = client.fetch(.{
+    .response_writer = &aw.writer,
+    ...
+});
+
+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 });
+```
+
+## 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":
+
+```zig
+outer: while (total_read < response_buf.len) {
+    var w: std.Io.Writer = .fixed(response_buf[total_read..]);
+    while (true) {
+        const n = tls_client.reader.stream(&w, .limited(remaining)) catch break :outer;
+        if (n != 0) {
+            total_read += n;
+            break;
+        }
+        // n == 0 means keep trying, not EOF
+    }
+}
+```
+
+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.