feat(relay): add opt-in newest-first thread windows

[kalvinnchau]

Summary

Add an opt-in, newest-first thread window to the authenticated HTTP query path.

A filter with thread_window: true returns:

• reply rows ordered by (created_at DESC, id ASC) with an exact composite cursor;
• optional bounded reactions, edits, deletions, and delete-of-aux closure;
• one relay-signed kind:39007 bounds event bound to the normalized host, authenticated reader, channel, root, request cursor, kinds, depth, limit, and aux choice.

Filters without the flag keep the existing oldest-first thread behavior. Channel windows and kind:39006 are unchanged. No client opts into this mode in this PR.

Why extend NIP-CW

NIP-CW already defines relay-computed, cursor-paged conversation views over extended NIP-01 filters. Thread windows use the same protocol ideas: ordinary signed rows, composite keyset pagination, optional aux closure, and relay-signed bounds. Adding a thread mode keeps those related wire contracts together instead of creating a second NIP with duplicated terminology and compatibility rules.

Extending a draft, optional NIP with an additive mode is normal protocol evolution. Existing fields and meanings are not reinterpreted:

• top_level: true remains channel mode;
• kind:39006 remains channel-window bounds;
• thread_window: true selects the new mode;
• kind:39007 has a distinct identity and root/request binding;
• extension-unaware clients never send the selector;
• legacy thread queries remain unchanged.

NIP-CW documents only the wire contract and relay semantics. Database plans, replica internals, and rollout procedures remain implementation concerns.

Why thread windows use independent modules

The implementation deliberately keeps thread_window.rs separate in buzz-core, buzz-db, and buzz-relay rather than adding branches throughout the existing channel-window path.

The modes share pagination concepts, but their invariants differ:

• channel mode selects top-level rows; thread mode requires one root and depths 1..=depth_limit;
• thread mode accepts only conversation row kinds and rejects unknown/conflicting fields;
• thread bounds bind the root and authenticated reader because cross-channel aux visibility can differ by reader;
• thread aux includes the root and requires complete two-hop closure;
• thread mode refreshes writer authorization before selection and before signing;
• historical cursor pages may use a proved replica transaction, but fallback must restart both aux hops on the writer;
• legacy thread traversal is oldest-first and must not inherit descending cursor semantics.

Forcing these rules into channel-window code would create a mode flag across parsing, SQL predicates, bounds construction, authorization, replica fallback, and tests. That abstraction would not remove complexity. It would distribute it. Separate modules keep each contract local and leave the established channel and legacy paths untouched.

Technical design

• Strict request parsing normalizes UUIDs, event IDs, kinds, defaults, and cursors before computing the response binding.
• SQL applies community, root, channel, depth, kind, deletion, and cursor predicates before limit + 1.
• Ordered metadata scanning plus exact event-key lookup avoids the stale-statistics plan that previously exceeded the four-second SQL budget on a 10k-reply thread.
• Aux work is bounded by target batches, query count, raw candidate count, response bytes, SQL timeouts, and one shared HTTP deadline.
• Fresh authorization-set comparison catches both grants and revocations during closure. The relay returns retryable 503 rather than signing an incomplete page.
• Replica failure permanently degrades the request to the writer and restarts closure from its original targets without resetting budgets.
• Migration 0049_thread_window_index.sql adds the mixed-direction index used by newest-first scans. It validates a prebuilt index and bounds startup lock/build time.

Tradeoffs

• The stale-statistics-safe plan is intentionally less clever. Measured warm 100k deep-cursor execution increased from roughly 0.30 ms to 4.80 ms, plus about 8 ms planning, in exchange for avoiding a reproduced multi-second timeout after rapid 10k-thread insertion.
• Bounds are authoritative only for the served page. There is no cross-page snapshot guarantee, and replica insertion coverage does not imply latest edit/deletion/aux visibility.
• Strict parsing rejects unsupported constraints instead of silently serving a different row set.
• Required aux closure fails closed. The relay does not omit aux and sign plausible-but-incomplete bounds.
• This PR ships relay capability only. Client rendering, retry UX, live-history overlap, and compatibility fallback remain separate work.

Related issue

No existing issue found. This work follows the thread-loading design and review discussion.

Testing

• cargo test -p buzz-core: 258 unit tests and 2 doctests passed.
• cargo check --workspace --all-targets: passed at the rebased implementation head.
• cargo test -p buzz-db: 131 non-PostgreSQL tests passed; 275 infrastructure tests were ignored as declared.
• Focused PostgreSQL migration/runtime regressions: 3/3 passed against an isolated PostgreSQL container, including both corrected migration-ledger tests.
• cargo fmt --all --check: passed.
• Pre-rebase feature validation passed 398/398 PostgreSQL tests, signed-wire multi-tenant/auth/pagination/aux/revocation probes, clean Compose boot/reboot, and full core tests.
• Independent HA validation exercised three relay pods and a physical PostgreSQL standby on the same runtime logic before the final documentation-only cleanup.
• Independent final-delta review confirmed exactly two changed files, byte-identical executable migration SQL after comments/diagnostic normalization, matching prebuild/catalog/recovery instructions, and git diff --check; no runtime receipts were relabeled to the new SHA.
• The pre-push hook ran repository checks but its Rust unit lane exited 100 without exposing an individual failed test in the captured multiplexed output. The independently run affected-package checks above passed; current-head repository CI remains required.

Known unrelated baseline behavior remains: the mesh-demo echo test can return 504, and same-second archive → unarchive can deduplicate its membership notification. Neither path is changed here.

[github-actions]

🔐 Codex Security Review

Status: review required for the current range.

The current range is 3b2e50b15c6afba3ff3b8fbe1bdf0a7a69d29f7b...0964ed71fe605daf9a700013a41eae8c6fc429ab.
A new review must complete for this exact range. When manual authorization
is required, a Block organization member must comment exactly
@buzz-security-review 0964ed71fe605daf9a700013a41eae8c6fc429ab to authorize a new review.
Any previous review applies only to its recorded range.

[wpfleger96]

🤖 hey @kalvinnchau, thanks for this. We did two independent source reviews plus a local E2E run against a real relay at 54c472a. Most of it held up well: strict opt-in parsing, legacy isolation, the mixed-direction cursor math, predicates applied before limit + 1, raw scan cursors surviving reconstruction failures, the replica upper-bound check plus two-hop restart, and the bounded migration with concurrent prebuild validation. The live run passed all four reply kinds, same-second ties across four pages with concurrent edits/deletes/new replies, independent verification of the 39007 signature and binding, the depth limits, and legacy compatibility.

I think three things need fixing before merge, and there are a few smaller items. Details are inline:

1. A batched /query can still return an earlier window's private rows and signed bounds after a later window in the same request has seen the reader's access revoked. We reproduced this live three times.
2. The aux byte budget only applies after fetch_all() has already loaded up to 1,001 full payloads (this is allocation math from the source, not a measured OOM).
3. A root whose kind isn't in ROW_KINDS gets a signed has_more: false with no rows, even when replies exist.

Smaller items: @> tag matching ignores position, budget exhaustion returns an opaque 500, and NIP-CW still doesn't document the legacy oldest-first thread path.

Not covered by the live run: physical replica lag/failover, a production-scale migration/load test, and any desktop/mobile adoption.

[wpfleger96]

🤖 Re-reviewed at 0964ed71fe605daf9a700013a41eae8c6fc429ab. All six earlier comments are addressed, so I'm approving.

We checked it two ways again. There was an independent source pass over d57270876 and 0964ed71f and the paths they touch. There was also a live rerun against an isolated relay built from this head, using only signed network operations. In the batch-revocation race, 36 attempts across the same-channel and different-channel variants came back as 11 clean 503s and 25 complete two-bounds 200s. None returned a partial response. The live run also covered the 40008 root (no bounds, with or without aux), 40 edits at exactly 256 KiB (a 503 with the reduce-work message, and aux-off recovers), both positional-tag lookalikes excluded, the shared reply/aux/batch budget, and the earlier journey/boundary regressions. CI at this head is green.

One small thing: the PR body still says 54c472a is the current head, so the runtime receipts there describe the old revision. It's worth refreshing before merge.