Feat/m0 zig 0 16 upgrade

[indykish]

Greptile Summary

This PR upgrades posthog-zig from Zig 0.15.2 to 0.16.0, bumping the library to v0.2.0 with a single user-visible breaking change: posthog.init() now accepts an io: std.Io argument between allocator and config. Internally, every concurrency primitive (std.Thread.Mutex/Condition → std.Io.Mutex + std.Io.Event), the HTTP client, timestamp sources, and the retry PRNG have been migrated to the new std.Io model, and the previous debug_threaded_io.? panic risk in retry.zig has been resolved by switching to a self-seeded thread-local PRNG.

Confidence Score: 5/5

Safe to merge — all remaining findings are P2 style cleanup with no correctness impact.

The migration is complete and consistent across all call sites. The previously flagged debug_threaded_io.? panic in retry.zig is fully resolved. Tests cover concurrency, overflow, TTL expiry, deadline short-circuit, and OOM paths. The only finding is dead code in a test file.

tests/caller_sim_test.zig (dead Counters struct)

Important Files Changed

Filename	Overview
src/client.zig	Public API updated: init() gains io: std.Io between allocator and config; all concurrency calls and serialization writers correctly updated for Zig 0.16.
src/batch.zig	std.Thread.Mutex/Condition replaced with std.Io.Mutex + std.Io.Event; waitForEventsOrTimeout uses Event.waitTimeout correctly; post-wake reset() ordering is safe under single-consumer contract.
src/flush.zig	Shutdown deadline logic, retry loop, and sleepForNs all updated to use Io.Clock.awake and io.sleep; saturating-mul overflow guards are correctly handled.
src/retry.zig	Previous debug_threaded_io.? panic risk fully resolved: threadRandom() now seeds from @intFromPtr(&rng_state) ^ (counter *% golden_ratio), eliminating Io dependency entirely.
src/transport.zig	postBatch and postDecide both gain an io parameter; std.http.Client now constructed with { .allocator, .io } and response buffered through Io.Writer.Allocating.
src/feature_flags.zig	FlagCache gains io: std.Io; std.Io.Mutex replaces std.Thread.Mutex; put() uses ensureUnusedCapacity + putAssumeCapacity to prevent post-remove OOM.
src/types.zig	nowMs and monotonicNs moved from std.time.* to std.Io.Clock.real/awake; Io.Writer.Allocating replaces io.Writer.Allocating throughout serialisation helpers.
build.zig.zon	Version bumped to 0.2.0, minimum_zig_version correctly updated to 0.16.0; published paths explicitly enumerate only consumer-facing docs.
tests/caller_sim_test.zig	Comprehensive offline caller-simulation tests updated for 0.16 API; minor dead code: Counters struct at line 484-498 is defined but never used.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant PostHogClient
    participant Queue
    participant FlushThread
    participant Transport

    Caller->>PostHogClient: init(allocator, io, config)
    PostHogClient->>Queue: Queue.init(allocator, io, ...)
    Note over Queue: Io.Mutex + Io.Event replace Thread.Mutex/Condition
    PostHogClient->>FlushThread: FlushThread.spawn(allocator, io, queue, cfg)

    loop Non-blocking hot path
        Caller->>PostHogClient: capture / identify / group
        PostHogClient->>Queue: enqueue(json)
        Queue-->>Queue: Io.Mutex.lock → arena.dupe → unlock
        alt count >= flush_at
            Queue->>FlushThread: Io.Event.set (wake signal)
        end
    end

    loop Background flush loop
        FlushThread->>Queue: waitForEventsOrTimeout (Io.Event.waitTimeout)
        FlushThread->>Queue: drain() → swap write/flush sides
        FlushThread->>Transport: postBatch(allocator, io, host, key, events)
        Note over Transport: std.http.Client{ .allocator, .io }
        Transport-->>FlushThread: HTTP status
        alt 5xx / 429 and retries remain
            FlushThread->>FlushThread: backoffNs (threadlocal PRNG) + io.sleep
        end
        FlushThread->>Queue: resetSide(idx)
    end

    Caller->>PostHogClient: deinit()
    PostHogClient->>FlushThread: stop(timeout_ms)
    FlushThread-->>FlushThread: shutdown deadline via Io.Clock.awake
    FlushThread->>FlushThread: final doFlush
    FlushThread-->>PostHogClient: thread.join()

Loading

Comments Outside Diff (3)

1. src/root.zig, line 5-7 (link)

   Stale module docstring missing io argument

   The module-level usage example still shows the old two-argument init signature. Anyone who copies it will get a compile error because init now requires three arguments (the new io: std.Io parameter between allocator and config).

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: src/root.zig
   Line: 5-7
   
   Comment:
   **Stale module docstring missing `io` argument**
   
   The module-level usage example still shows the old two-argument `init` signature. Anyone who copies it will get a compile error because `init` now requires three arguments (the new `io: std.Io` parameter between `allocator` and `config`).
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

2. src/feature_flags.zig, line 68-76 (link)

   Spurious eviction on update when cache is at capacity

   When put() is called at capacity (count == max_entries) for a distinct_id that already exists in the cache, the eviction block runs unconditionally and may remove an arbitrary other user's entry. The update path then also removes the old entry for the same distinct_id, leaving the cache at max_entries - 1 with a valid entry needlessly dropped.

   Concrete path: cache full with {"user_1": A, "user_2": B}, call put("user_1", new) → eviction iterator picks "user_2" → B is freed → fetchRemove("user_1") removes A → put("user_1", new) → cache is {"user_1": new} (1 entry, not 2). "user_2" must make a fresh network round-trip on next access.

   The fix is to skip eviction when the target key is already present:

   if (!self.entries.contains(distinct_id) and self.entries.count() >= self.max_entries) {
       // evict one entry ...
   }

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: src/feature_flags.zig
   Line: 68-76
   
   Comment:
   **Spurious eviction on update when cache is at capacity**
   
   When `put()` is called at capacity (`count == max_entries`) for a `distinct_id` that already exists in the cache, the eviction block runs unconditionally and may remove an arbitrary *other* user's entry. The update path then also removes the old entry for the same `distinct_id`, leaving the cache at `max_entries - 1` with a valid entry needlessly dropped.
   
   Concrete path: cache full with `{"user_1": A, "user_2": B}`, call `put("user_1", new)` → eviction iterator picks `"user_2"` → B is freed → `fetchRemove("user_1")` removes A → `put("user_1", new)` → cache is `{"user_1": new}` (1 entry, not 2). `"user_2"` must make a fresh network round-trip on next access.
   
   The fix is to skip eviction when the target key is already present:
   
   ```zig
   if (!self.entries.contains(distinct_id) and self.entries.count() >= self.max_entries) {
       // evict one entry ...
   }
   ```
   
   How can I resolve this? If you propose a fix, please make it concise.

3. src/flush.zig, line 76-82 (link)

   stop() ignores timeout_ms — thread.join() has no deadline

   The timeout_ms parameter is silently discarded and thread.join() blocks indefinitely. If the network is unresponsive during the final doFlush call (which can retry up to max_retries times with up to 30s backoff each), deinit() will hang for minutes. The // v0.2 comment acknowledges this is deferred, but callers who set a short shutdown_flush_timeout_ms will not get the bounded shutdown they expect.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: src/flush.zig
   Line: 76-82
   
   Comment:
   **`stop()` ignores `timeout_ms` — `thread.join()` has no deadline**
   
   The `timeout_ms` parameter is silently discarded and `thread.join()` blocks indefinitely. If the network is unresponsive during the final `doFlush` call (which can retry up to `max_retries` times with up to 30s backoff each), `deinit()` will hang for minutes. The `// v0.2` comment acknowledges this is deferred, but callers who set a short `shutdown_flush_timeout_ms` will not get the bounded shutdown they expect.
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: tests/caller_sim_test.zig
Line: 484-499

Comment:
**Dead `Counters` struct is never used**

The `Counters` struct (including its `callback` method) and the `_` discard on line 499 are never instantiated or called. The test was refactored to use the `S` struct instead, but this dead code wasn't removed. The local variables declared at lines 480–482 are still used (assigned and asserted at the bottom of the test), but the struct definition itself is unreachable.

```suggestion
    // Use package-level atomics since the callback is a bare fn pointer
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (8): Last reviewed commit: "refactor: address greptile P2s + scrub 0..." | Re-trigger Greptile}

[indykish]

Addressed three additional greptile findings in c5bd292 (in addition to the retry.zig thread already replied to):

src/root.zig:5-7 — stale module docstring
Updated the usage example to the 3-arg form so copy-paste from the header compiles:

var client = try posthog.init(allocator, posthog.defaultIo(), .{ .api_key = "phc_..." });

src/feature_flags.zig:68-76 — spurious eviction on update at capacity
Guarded the eviction block on !entries.contains(distinct_id). When put() is replacing an existing key, the fetchRemove path below handles it in place without growing the map, so evicting a stranger is pure loss. Added a regression test (feature flags: re-put at capacity does not evict other entries) that fills to capacity, re-puts an existing key, and asserts the other user's entry survives.

src/flush.zig:76-82 — stop(timeout_ms) ignored the timeout
stop() now publishes now + timeout_ms on ctx.shutdown_deadline_ns (atomic, awake clock) before setting shutdown and signalling. doFlush checks the deadline at the top of every retry iteration and short-circuits to .dropped once crossed, so deinit() no longer blocks for minutes under retry backoff. Kernel join() itself is not timed — Zig 0.16 has no timed std.Thread.join and detaching would leak ctx — but the deadline covers the user-visible concern (bounded network blocking); join is fast once the drain exits. New test flush: stop() honours timeout_ms deadline in retry loop asserts zero POST attempts when the deadline is already in the past.

70/70 tests pass on Zig 0.16.0.

[indykish]

Addressed two greptile findings from the second round in d44f953:

src/feature_flags.zig:80-86 — cache entry lost on post-fetchRemove OOM
put() now calls self.entries.ensureUnusedCapacity(1) up front, then fetchRemove, then putAssumeCapacity. The slot is reserved before the old entry is dropped, so an OOM anywhere in the path either fails fast (before any mutation) or cannot fail at all (after ensureUnusedCapacity). No more silent cache-disabling under memory pressure.

src/flush.zig:91-94 — unsigned multiply overflow in stop() deadline
Switched to saturating multiply: timeout_ms *| std.time.ns_per_ms. Caps at u64::MAX on absurd inputs instead of wrapping silently in ReleaseFast or panicking in Debug; the subsequent @intCast(... ) i64 still polices the ~292-year ceiling.

70/70 tests pass on Zig 0.16.0.

[indykish]

Addressed three greptile findings from round 3 in b580429:

build.zig.zon:7-14 — docs/ excluded from package paths
Added docs and CHANGELOG.md to .paths. zig fetch consumers now receive docs/ZIG_0_15_COMPAT.md and docs/MIGRATION_ZIG_0_16.md that README links as required migration references — previously those links 404'd in the installed tree.

src/feature_flags.zig:125-128 — getPayload conflated OOM with cache miss
Changed the signature to std.mem.Allocator.Error!?[]u8 and replaced catch null with try. Callers (client.getFeatureFlagPayload) treat null as a clean cache miss and re-fetch from /decide/, so the previous swallow silently converted memory pressure into network pressure. Both call sites in client.zig and the unit test updated with try.

src/root.zig:63-65 — defaultIo() bare .? panic
Replaced with an explicit @panic carrying a diagnostic that points freestanding / embedded / custom-harness callers at passing their own std.Io (e.g. from a std.Io.Threaded they own) instead of calling this helper. No change for normal executable builds where start.zig populates debug_threaded_io.

70/70 tests pass on Zig 0.16.0.

[indykish]

Addressed the self-review warnings and observations in 16c077e, plus a docs-layout change per request:

Warnings

• build.zig.zon: .paths now enumerates user-facing docs individually instead of including the whole docs/ tree — keeps project-management specs (docs/v1/{pending,active,done}/) and agent logs (docs/nostromo/) out of the published package.
• src/flush.zig: flushLoop uses saturating multiply (flush_interval_ms *| std.time.ns_per_ms), matching the stop() fix. No more silent u64 wrap on absurd intervals.

Observations

• src/flush.zig: comment documenting the intentional i96 + i64 mix in stop() (Zig 0.16 auto-widens; final @intCast to i64 is safe for ~292 years of monotonic boot time).
• src/batch.zig: comment documenting the intentional unlock-before-wake.set ordering in enqueue — avoids a thundering-herd where the woken flush thread would immediately block on the mutex we still hold.
• src/feature_flags.zig: new regression test getPayload propagates OOM instead of swallowing it uses std.testing.FailingAllocator to verify the new Allocator.Error!?[]u8 signature actually surfaces OOM instead of regressing to catch null.

Docs layout

• Moved docs/MIGRATION_ZIG_0_16.md → docs/v1/MIGRATION_ZIG_0_16.md and docs/ZIG_0_15_COMPAT.md → docs/v1/ZIG_0_15_COMPAT.md. README, CHANGELOG, and .paths follow. The one self-link between the two guides was already relative so it still resolves.
• Created empty docs/nostromo/ (with .gitkeep) to match the ~/Projects/usezombie/docs/ convention; it will carry future agent session logs.

71/71 tests pass on Zig 0.16.0 (added one new test for the OOM path).

[indykish]

Fixed in 8ac6605. PostHogClient.init docstring now points callers at the public posthog.defaultIo() helper (which wraps the raw access with a friendly panic message) instead of std.Options.debug_threaded_io.?.io(). No more leaking the internal Zig 0.16 accessor through a copy-pasted docstring.

[indykish]

Addressed both P2s plus the broader "scrub 0.15-era comments" ask in b63596f:

P2 — src/types.zig:152 stale Zig 0.15 comment
Rewritten to describe the forward-facing rule: formatIso8601 only handles post-epoch timestamps, so the unsigned cast keeps output deterministic regardless of any future signed zero-pad formatting changes in Zig.

P2 — src/flush.zig:96 @intCast panic for saturated timeout
timeout_ms *| std.time.ns_per_ms is now clamped with @min(..., @as(u64, std.math.maxInt(i64))) before the @intCast to i64. Contract: any timeout_ms is accepted; impossibly large values resolve to an effectively-infinite deadline, never a Debug-mode panic.

Comment scrub
Forward-facing rewrites across src/batch.zig, src/client.zig, src/retry.zig, src/types.zig, tests/caller_sim_test.zig, tests/integration_test.zig — removed the "Zig 0.16 removed X" / "post-0.15" / "0.15 bracketed each call" framing in favour of present-tense descriptions of the current design. The historical record of the migration still lives in docs/v1/MIGRATION_ZIG_0_16.md, which is where it belongs.

78/78 tests pass on Zig 0.16.0.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!