vanken 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6bfbb1b288a09cb5fb170bed462adb00f4ae86aa21ee62c247e9e2cefe2aaa97
+  data.tar.gz: 3f8f754621be04e6fc2a4dac72abae4c10f57a8d3524f018c67825abe18b4e8a
+SHA512:
+  metadata.gz: bc1c63f6df229fbb85db6e00cd69059faa16a69f91469f5cd8a3d7d6ad7b8e0bcce3068ed31ebb4533c77906188b3448026a6e5a1cfe581a2d1f5d4fb058cce0
+  data.tar.gz: 370e198b35f3c4bb080f773b026ae6005c3457bd4412d9be8b13e1ea868c182b0919cf8d4b041325231a44f1ec8bf2d556dc15eb01ba1bbff47893cde91c6d49

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,84 @@
+# Vanken
+
+A packet capture and inspection desktop application written in Ruby. Vanken reads pcap and pcapng files, displays a virtual packet list alongside protocol details and bytes, and filters captures with its own display filter language.
+
+Packet acquisition runs in a separate helper; ordered packet analysis runs in another unprivileged process. The desktop application runs as a regular user. Raw frames and summaries are spooled to private files; slow filters use worker processes.
+
+## Requirements
+
+- Ruby 3.3 or newer; Ruby 3.4 or 4.0 with YJIT is recommended.
+- Linux with a desktop session, or macOS. File inspection is also available on Windows; live capture uses Linux packet sockets or macOS BPF.
+- Linux desktop dependencies: Vulkan loader and drivers, fonts, and `zenity` for native file dialogs. On Ubuntu: `sudo apt install libvulkan1 mesa-vulkan-drivers fonts-dejavu-core fonts-noto-cjk zenity`.
+
+## Run from source
+
+```sh
+git clone https://github.com/ydah/vanken.git
+cd vanken
+bundle install
+bundle exec exe/vanken capture.pcapng
+```
+
+Initial RubyGems publication is pending. To install a locally built gem:
+
+```sh
+gem build --strict vanken.gemspec
+gem install ./vanken-0.1.0.gem
+vanken capture.pcapng
+```
+
+Strict gem builds require RubyGems 4.0.16 or newer; older versions reject the pinned redhound prerelease with a recommendation warning.
+
+Open a capture from the toolbar, a recent file, or a file drop. Select a packet to inspect its protocol tree and bytes. Selecting a field highlights its bytes; selecting bytes finds the corresponding field. Columns can be sorted, resized, hidden, and reordered. Themes, font size, split positions, columns, and filter history persist between sessions.
+
+Enter a display filter and choose Apply, or press Enter in the filter field:
+
+```text
+tcp.port == 443
+ip.addr in {192.0.2.0/24, 198.51.100.5}
+tcp.flags.syn == true && tcp.flags.ack == false
+http.host contains "example"
+frame.len > 1000 && !udp
+```
+
+Vanken display filters (VDF) and acquisition filters (BPF) are separate languages. See [display filters](docs/filters.md) for operators, types, and repeated fields.
+
+## Capture
+
+Choose Start, select an interface, and optionally set a BPF acquisition filter. Stop preserves captured packets for inspection and saving. Vanken asks before discarding an unsaved capture.
+
+```sh
+bundle exec exe/vanken-capture --list-interfaces
+bundle exec exe/vanken-capture --check --interface lo
+```
+
+Direct acquisition works when the account already has permission. Privileged launching requires a root-owned installation with a fixed interpreter and dependencies; see [capture helper setup](packaging/README.md). Run the desktop application as a regular user.
+
+## Command line
+
+```sh
+bundle exec exe/vanken --headless --read capture.pcap --print-columns --filter 'tcp.port == 443'
+bundle exec exe/vanken --tui capture.pcapng
+bundle exec exe/vanken --headless --smoke
+```
+
+`--no-yjit` disables default YJIT activation. `--debug` enables debug logging. Preferences use safe YAML in the platform's user configuration directory; logs rotate without retaining raw packet bytes.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake rbs
+bundle exec ruby script/generate_fixtures.rb --performance
+bundle exec ruby script/benchmark.rb
+script/capture-ci.sh
+```
+
+To develop with a sibling Zaniah checkout, set `VANKEN_ZANIAH_PATH=../zaniah` when running Bundler. Production dependencies are redhound `2.0.0.rc2` and Zaniah `~> 0.12.3`, including fixes for growing memory use and repeated style allocations during redraws.
+
+See [upstream contracts](docs/upstream.md), [measured performance](docs/performance.md), and [release procedure](docs/releases.md). Version 0.1 implements the file inspection, acquisition, and display filter milestones. Statistics, stream following, coloring, profiles, and later extensions are scheduled for subsequent releases.
+
+## License
+
+[MIT](LICENSE.txt).

data/docs/filters.md

@@ -0,0 +1,25 @@
+# Display filters
+
+VDF is parsed without evaluating Ruby. Acquisition uses BPF, compiled independently before the helper starts.
+
+| Operation | Syntax |
+| --- | --- |
+| Presence | `tcp`, `http.host` |
+| Boolean logic | `!tcp`, `tcp && ip`, `tcp || udp`; `not`, `and`, `or` also work |
+| Comparisons | `==`, `!=`, `~=`, `<`, `<=`, `>`, `>=`; `eq`, `ne`, `any_ne`, `lt`, `le`, `gt`, `ge` also work |
+| Contains | `http.host contains "example"` |
+| Regular expression | `http.host matches "^www[.]"` |
+| Membership and inclusive ranges | `tcp.port in {80, 443, 8000..8080}` |
+| Nonzero bitmask | `tcp.flags & 0x12` |
+
+Negation binds before conjunction, which binds before disjunction. Mixing conjunction and disjunction without parentheses produces a warning. Syntax errors identify the input position. Unknown fields warn and behave as missing fields.
+
+Inputs are bounded to 8192 bytes, 511 tokens, and 64 nested expressions so malformed expressions cannot exhaust a worker stack.
+
+Literals include decimal and hexadecimal integers, floats, booleans, IPv4/IPv6 addresses, CIDR prefixes, MAC addresses, quoted strings, and hexadecimal bytes. Strings support escaped quotes, backslashes, and `\xNN` byte escapes. Regular expressions have a 100 ms timeout.
+
+Repeated layers and aliases can supply multiple values: `tcp.port` contains source and destination ports; `ip.addr` contains source and destination addresses. `==` succeeds when any value matches, `!=` when no value matches (including a missing field), and `~=` when any value differs. Other comparisons on missing fields are false. A present boolean field whose value is false passes a presence test.
+
+Frame metadata, columns, protocol presence, and persisted analysis annotations can be filtered without dissection. Other fields use workers in 10,000-frame batches. Results appear progressively; replacing the expression cancels the preceding scan. Acquisition continues during filtering.
+
+Select a protocol field to apply or prepare its expression from the Filter menu, including AND/OR/negation combinations. Preparing changes the input without applying it. Named filters and recent expressions persist.

data/docs/performance.md

@@ -0,0 +1,113 @@
+# Performance measurements
+
+Run the production receiver, analyzer process, display filters, and UI benchmark:
+
+```sh
+bundle exec ruby --yjit script/benchmark.rb 1000000 120 4
+bundle exec ruby --yjit script/native-smoke.rb
+script/capture-ci.sh
+```
+
+The benchmark arguments are packet count, UI samples, and slow-filter worker count. Zero workers skips the slow filter. Functional failures raise; JSON reports each numeric performance target separately. For a sibling Zaniah checkout, set `VANKEN_ZANIAH_PATH=../zaniah` when installing and running the bundle.
+
+## Workload and measurement boundaries
+
+The synthetic source yields valid 58-byte Ethernet/IPv4/UDP frames individually, reusing one frozen byte string. Addresses and ports are constant. Receiver timing includes the production disk spool and flushes. Document timing includes reception, ordered stateful analysis in an unprivileged child process, packed IPC batches, catalog updates, and persisted annotations and summaries. The fast filter `udp && udp.port == 54321` matches every frame. The slow filter `ip.ttl == 64` uses four real named `Capture::FilterWorker` processes; timing includes cold worker startup.
+
+Retained heap is the difference in `ObjectSpace.memsize_of_all` after GC, divided by frame count. It excludes reserved heap pages, native allocations, child heaps, and filesystem cache. It is not RSS. Actual RSS comes from `ps -o rss= -p PID`. Document analysis samples parent and analyzer RSS every 250 ms and reports their combined peak increment, subtracting parent RSS before ingest and the first child sample. Child startup after that first sample contributes to the increment. The receiver-only benchmark now runs in a separate process so its allocator pages do not inflate the document baseline. A 50-frame warm-up initializes document caches. After-filter RSS is also reported. Slow-filter worker RSS and filesystem cache are excluded; unavailable RSS is `null`, never a passing result.
+
+The component UI measurement scrolls a production virtual table with one million logical rows and 20 visible rows. It uses the bundled Abel font, a 1200 × 420 viewport, and 20 warm-up frames. This measurement excludes application chrome and packet row IO.
+
+Complete-application measurements use `Application`, `MainView`, real stored packets, system fonts, and a 1280 × 800 viewport. Packet 1 is selected, IPv4 is expanded, and TTL is highlighted in both details and bytes. After 100 warm-up frames, the benchmark measures 120 renders. The growing scenario releases 25,000 additional frames at 5,000 frames/s, follows the packet-list tail, and verifies actual source progress during sampling. Counts are checked after the whole capture drains.
+
+`render(present: false)` includes layout, prepaint, scene paint, glyph shaping, and accessibility updates. Scene timing ends after paint and is reported separately, matching the design's `Inspection.snapshot(window).frame` criterion. Headless measurements exclude pixel rasterization, native events, and GPU presentation. Native smoke reports both scene time and total tick time, including presentation.
+
+## Recorded arm64 results
+
+Measured on 2026-10-02 using Ruby 4.0.6, YJIT, `arm64-darwin25`, and Zaniah 0.12.0. These are individual workstation runs, not isolated-machine medians. Receiver, analysis, memory, and fast-filter figures below come from fresh processes after removing the duplicate in-memory frame index. Slow-filter and UI figures come from the earlier complete benchmark; a six-second focused test overlapped the start of that run, but not its UI phases.
+
+| Measurement | Result | Target |
+| --- | ---: | ---: |
+| Receiver, 1,000,000 frames | 380,823 frames/s | ≥ 100,000 |
+| Ingest and analyze, 1,000,000 frames | 17,012 frames/s; 58.7827 s | ≥ 15,000 |
+| Fast filter, 1,000,000 matches | 0.5473 s | ≤ 3 s |
+| Slow filter, four workers, 1,000,000 matches | 5.2345 s | ≤ 60 s |
+| Retained parent heap before/after fast filter | 67.22 / 75.23 B per frame | Heap proxy only |
+| Parent RSS increment after analysis | 183.68 B per frame | ≤ 200 |
+| Sampled parent-plus-analyzer RSS increment | 186.27 B per frame | ≤ 200 |
+| Parent RSS increment after fast filtering | 209.88 B per frame | ≤ 200; exceeded |
+| Virtual table, render p95 | 15.577 ms | ≤ 33 ms |
+| Virtual table during ingestion, render p95 | 13.880 ms | ≤ 33 ms |
+| Complete application, scene p95 | 29.186 ms | ≤ 33 ms |
+| Complete application during ingestion, scene p95 | 30.373 ms | ≤ 33 ms |
+| Complete application during ingestion, total render p95 | 31.479 ms | Reported separately |
+
+All 120 growing-application samples overlapped actual traffic: 13,200 frames were produced in 2.6471 seconds (4,986.62 frames/s), while analyzed rows grew from 512 to 13,568. All 25,256 frames, including the initial 256, completed in 5.0219 seconds without loss.
+
+A separate native 120-sample run produced 17,103 frames in 3.4840 seconds (4,909 frames/s, within the 256-frame pacing tolerance). Durable rows grew from 768 to 17,920 and analyzed rows from 768 to 7,357 during sampling. Scene p95 was 28.862 ms; total native tick p95 was 44.518 ms. The complete 25,000-frame capture drained without loss. This short run demonstrates scene responsiveness, but does not establish sustained backlog limits.
+
+The former in-process analyzer exceeded 33 ms during correctly paced native ingestion. The default analyzer now runs in a separate unprivileged Ruby process, as required by the design's alternative. The child preserves analysis order and state, sends bounded batches through private pipes, and retains no complete second column store. The UI reads cached rows asynchronously.
+
+The fresh parent RSS baseline was 48,922,624 bytes, rising to 232,603,648 bytes after analysis and 258,801,664 after filtering. Frame metadata now stays on disk, removing approximately 33.55 MB of retained heap for one million frames. IPC reserves its exact payload size and reuses one read buffer; fast port predicates read packed fields directly, and metadata is fetched only when a filter uses it. Historical filter results reserve their known maximum array capacity once. The filter added 8.01 MB of retained heap but 26.20 MB of RSS; GC pages and JIT code explain only part of the difference. The additional after-filter RSS target remains exceeded on this macOS run.
+
+## Recorded x86_64 results
+
+The Linux shared runner used Ruby 3.4.10 with YJIT and public Zaniah 0.12.1. [The complete benchmark and 5,000 deterministic fuzz cases](https://github.com/ydah/vanken/actions/runs/36975615332), at Vanken commit `5de8854`, finished without functional errors. These measurements precede the visible-row batching change. Numeric targets are reported separately from job success.
+
+| Measurement | Result | Target |
+| --- | ---: | ---: |
+| Receiver, 1,000,000 frames | 219,407 frames/s | ≥ 100,000 |
+| Ingest and analyze, 1,000,000 frames | 4,849 frames/s; 206.2345 s | ≥ 15,000; missed |
+| Parent / combined / after-filter RSS increment | 81.56 / 85.64 / 92.03 B per frame | ≤ 200 |
+| Fast / four-worker slow filter | 1.8402 / 21.0254 s | ≤ 3 / 60 s |
+| Static full application, total / scene render p95 | 67.705 / 66.455 ms | ≤ 33 ms; missed |
+| Growing full application, scene p95 | 67.410 ms | ≤ 33 ms; missed |
+
+The synthetic growing source reached only 312.58 frames/s during sampling, so this run does not demonstrate responsiveness at 5,000 frames/s. An independent [native run](https://github.com/ydah/vanken/actions/runs/36979552426), at commit `8fcce51` after visible-row batching, delivered 4,972.28 frames/s within the pacing allowance. Active scene p95 was 53.057 ms, missing the target; all 25,256 frames completed without loss. Before the focus fix, the corresponding shared-runner scene p95 measurements were 331.801 ms for the growing application and 230.321 ms for native ingestion.
+
+Investigation reproduced a Zaniah focus-tree retention bug: a three-row tree retained 18 row handles after six renders. The fix included in Zaniah 0.12.1 releases render-created parent links between frames while preserving manual hierarchies. The same Linux arm64 container, Ruby 3.4.11 with YJIT, UID 1000, fonts, 4,096-packet document, 100 warm renders, and 120 scrolling samples were measured before and after changing only the Dispatcher implementation:
+
+| Measurement | Before fix | After fix |
+| --- | ---: | ---: |
+| Total render p95 | 170.473 ms | 23.626 ms |
+| Scene p95 | 170.023 ms | 22.585 ms |
+| Maximum total render | 207.739 ms | 26.533 ms |
+| GC p95 | 148.697 ms | 6.289 ms |
+| Major GC during 120 samples | 15 | 0 |
+| Samples exceeding 33 ms | 43 | 0 |
+
+Per-frame allocations remained approximately 84,600 objects, supporting retained old rows as the cause of expensive GC. The three-row reproduction now retained exactly three current handles after each render, with no obsolete handles. This static arm64 diagnostic establishes the fix's effect; it does not substitute for x86_64 or sustained live-capture verification.
+
+Zaniah 0.12.2 avoids rebuilding default style values during merging; 0.12.3 removes a duplicate style merge from element updates. A separate macOS arm64 diagnostic used the actual 256-frame MainView, selected IPv4 TTL, the real text renderer, 40 warm renders, and 20 samples per variant. Applying and reverting each exact implementation changed allocations per render from 71,333 to 67,083 and back, then from 67,083 to 63,918 and back. The combined reduction was 10.4%. Nested element bounds and raw scene commands matched in both directions. Timing varied between runs, so this diagnostic establishes allocation savings, not a stable latency improvement or a passing live-capture target.
+
+## Linux capture and operation latency
+
+`script/capture-ci.sh` uses an isolated Linux network namespace, a root-owned capture helper, and a UID 1000 UI process. It sends 1,500,000 numbered UDP datagrams at 5,000 frames/s for 300 seconds. The helper uses an incoming packet socket and `udp dst port 54321`; a UDP sink prevents ICMP responses. After shutdown and drain, sent, kernel received, helper captured, durable, and analyzed counts must agree, and dropped, interface-dropped, and freeze counts must all be zero.
+
+The live UI follows the production `Application.run` loop: drain foreground work, tick the window, then wait for work when the window is clean. Only actual rendered frames enter latency samples. Document growth is checked between rendered frames during the independently measured sender interval. Forced redraws remain in the component and static-render benchmarks above. A [previous five-minute forced-redraw stress run](https://github.com/ydah/vanken/actions/runs/36977817521), at commit `19b5fe1`, timed out with 1,485,655 kernel drops; it does not establish production-loop capture integrity.
+
+The [first production-loop five-minute run](https://github.com/ydah/vanken/actions/runs/36979552791), at commit `8fcce51`, also failed. The sender delivered 1,500,000 frames at 4,999.9985 frames/s; 722,788 were captured and durable, 777,212 were dropped by the kernel, and 645,120 were analyzed when the 390-second deadline expired. The first file row took 735.646 ms, while the slowest selection took 147.265 ms. These results must not be treated as a passing live-capture or selection-latency gate.
+
+After publishing tail counts together with prepared rows, the [next run](https://github.com/ydah/vanken/actions/runs/36981466284), at commit `a0215b4` with Zaniah 0.12.1, received, captured, and durably stored all 1,500,000 frames at 4,999.9986 frames/s. Kernel drops, interface drops, and freezes were all zero. Analysis reached 974,080 frames when the former 390-second deadline expired, so final analysis equality remained unverified in that run. Full-scene p95 across its 2,070 actual renders was 112.871 ms; this includes post-traffic drain frames and exceeds the 33 ms target. The first file row took 752.545 ms and the slowest selection 134.829 ms.
+
+The integrity check now permits up to 600 seconds of analysis drain after the scheduled traffic duration, fails after 90 seconds without capture, spool, or analysis progress, and records actual post-traffic analysis time. This separates lossless capture verification from slower shared-runner analysis. Sender pacing, exact final count equality, drop checks, and reported numeric performance targets are unchanged; a long drain is not evidence that throughput or responsiveness targets passed.
+
+The [completed integrity run](https://github.com/ydah/vanken/actions/runs/36982911969), at commit `a7f0182`, used Ruby 3.4.11 with YJIT, public Zaniah 0.12.1, and UID/EUID 1000 on the shared x86_64 Linux runner. The sender delivered all 1,500,000 frames over 300.0001 seconds at 4,999.9989 frames/s. Kernel received, helper captured, durable, and final analyzed counts were each exactly 1,500,000; kernel drops, interface drops, and freezes were zero. Analysis completed 301.557 seconds after traffic ended. The maximum sampled analyzer backlog was 864,256 frames. Capture integrity and five-minute sender pacing passed; analysis throughput remains below its target on this runner.
+
+During actual traffic, 2,014 frames rendered and 1,992 showed analyzed-row growth. Scene p95 was 117.226 ms, exceeding 33 ms; total render p95 was 119.103 ms. The same run showed the first row of a 100,000,032-byte file in 641.359 ms, passing the one-second target, but its 20 selections had p95 121.997 ms and maximum 134.433 ms, exceeding 50 ms. A successful workflow therefore confirms functional integrity, not every numeric performance target. Shared-runner analysis and UI latency, together with the macOS after-filter RSS excess above, remain documented constraints for the initial release. Follow-up profiling should first address per-row analysis and layout allocations under the same measured workloads.
+
+JSON evidence includes actual sender rate, UI scene p95 during traffic, and one-second backlog samples. Kernel pending derives from the helper's statistics timestamp. Helper-to-durable compares that sample with a later GUI count and can be negative; it is not an atomic pipe-depth measurement. Final counts are exact. The workflow uploads evidence even on failure.
+
+The same script creates a capture of at least 100 MB, measures the open operation through the render showing its first UDP row, then selects 20 different packets while loading continues. The newly generated file is in the OS page cache; this is not a cold-disk test. Each selection must show both detail and byte panes; the elapsed time ends at the render that produced the verified scene. Subsequent Inspection assertion time is reported separately. Targets are first row ≤ 1 second and every selection ≤ 50 ms. To measure only these operations:
+
+```sh
+bundle exec ruby --yjit -Ilib script/capture-performance.rb --ui-only
+```
+
+On macOS arm64, Ruby 4.0.6 with YJIT and public Zaniah 0.12.1, a clean 100,000,032-byte capture containing 1,388,889 frames produced its first row in 300.377 ms, with 512 frames analyzed. Twenty different packet selections had p50 20.482 ms, p95 40.513 ms, and maximum 45.276 ms; the first selection took 40.403 ms. Both the first-row and every-selection targets passed in this single run. Pixel rasterization and native presentation were excluded.
+
+The final single-run check with public Zaniah 0.12.3 and the same Ruby, platform, viewport, and clean file workload produced its first row in 287.933 ms, with 256 frames analyzed. Twenty distinct selections had p50 15.728 ms, p95 31.424 ms, and maximum 39.525 ms. Both operation targets passed. The report records the actual installed Zaniah version; this result does not replace the slower shared-Linux-runner measurements above.
+
+Before visible-row batching, the same operation failed its first selection at 105.252 ms. A separate diagnostic reproduced a 107.234 ms background queue wait behind 11 row jobs, while actual detail analysis took 2.677 ms and byte reading 0.129 ms. Nine intermediate renders consumed most of that wait. PacketSource now collects visible-row requests after rendering, fetches them in one background job, and publishes their values in one foreground update. The passing run followed this runtime change; the earlier failure remains part of the evidence.
+
+The native and synthetic runs above do not substitute for this five-minute Linux capture test. Varied addresses, large TCP flow sets, reassembly, and plugins are outside the repeated-UDP benchmark's scope.

data/docs/releases.md

@@ -0,0 +1,15 @@
+# Releases
+
+Work is committed on main. Release notes and CHANGELOG entries include only user-visible changes. Documentation and maintenance changes alone do not trigger a release.
+
+Before tagging, run `bundle exec rake`, verify generated RBS is current, run privileged capture and benchmarks, perform native smoke, and build the gem strictly. Version, tag, gemspec dependencies, and lockfile must agree. Exclude captures, spools, test artifacts, local dependencies, and credentials from the gem.
+
+Initial 0.1.0 notes are exactly `Initial release.`. Publication is paused until the owner publishes the first RubyGem and configures trusted publishing. No initial release tag is pushed automatically.
+
+For the first publication, run `gem push pkg/vanken-0.1.0.gem`, then configure the publisher identity below. Tagging `v0.1.0` afterwards runs validation and creates the GitHub release; the job skips uploading a version already present on RubyGems.
+
+Subsequent `vX.Y.Z` tags trigger `.github/workflows/release.yml`, based on the Canopus release job. It verifies version, runs checks, builds the gem, publishes with RubyGems trusted publishing, and creates GitHub release notes from CHANGELOG.
+
+Trusted publisher identity: owner `ydah`, repository `vanken`, workflow `release.yml`, GitHub environment `release`.
+
+The design milestones are 0.1 for file inspection, capture, and filters; 0.2 for coloring, search, stream following, statistics, and analysis extensions; and 0.3 for profiles, localization, permission packaging, recovery UI, and additional capture conveniences. Work stops at the initial publication gate before the later milestones.

data/docs/upstream.md

@@ -0,0 +1,32 @@
+# Architecture and dependency contracts
+
+The architecture test keeps redhound references inside Gateway and the helper, and Zaniah references inside UI. Core stores and VDF do not depend on rendering. App::Document coordinates reception, ordered analysis, filter jobs, selection data, and atomic saves.
+
+The receiver writes frames.bin and frames.idx. A separate unprivileged Ruby process reads durable records and performs ordered, stateful analysis once per frame. Private pipes return packed batches of up to 256 frames; the document writes columns, annotations, summaries, and reassembled details before publishing the batch count. Filter changes reevaluate the current batch without repeating stateful analysis. Reception flushes every 256 frames or 50 ms, including idle periods. Final flush and analyzer drain retain the complete tail. UI notifications are limited to ten per second. Detail dissection, row reads, sorting, saving, and scanning run outside UI callbacks.
+
+The disk index uses 32 bytes per frame: `Q<L<L<q<S<S<Cx3` packs offset, captured length, original length, nanosecond timestamp, link type, interface index, direction, and reserved bytes. A separate read handle accesses durable records without retaining a second index in memory or moving the writer. Recovery scans one record at a time. Columns and annotations use compact 32-byte records and intern strings. Summaries and their 8-byte offsets are stored on disk; ordinary details are lazy. Reassembled details preserve the original analysis result. Spool directories use mode 0700, files 0600. Recovery rejects symlinks and incomplete records.
+
+Slow scans use a named ProcessPool handler with JSON-compatible immutable request data and a read-only spool reader. Workers do not run stateful analysis or modify the spool. Cancellation and generation checks stop old jobs from replacing current results.
+
+## redhound 2.0.0.rc2
+
+| Contract | Adapter and checks |
+| --- | --- |
+| `Redhound.open`, `next_packet(timeout:)`, `stopped?`, `stop`, `close` | FileReader; pcap/pcapng nanosecond round trips |
+| `Redhound.dissect`, private registry copy, engine assignment | Dissector; decoding and field catalogs |
+| Packet layers, field_values, summary, meta; fields, diagnostics, offsets | PacketView and DetailBuilder; stable IDs, escaped literals, repeated fields |
+| `Analysis::Session.new(stats: [], max_state_bytes:, max_flows:)`, update, finish | Analyzer; stream, budget, relative sequence, expert annotations |
+| Capture::Interface, writers, Capture::Stats | FileWriter; interface preservation and mixed-link pcap rejection |
+| Capture.interfaces, Capture.open, BPF compiler/verifier | Interfaces, LiveCapture, CaptureFilter; privileged integration |
+
+Regular files use the upstream reader directly. For pipes, FileReader supplies a buffered binary IO object to public `Redhound.open`, without replacing its parser or using private upstream classes. The adapter reads up to 64 KiB and waits only when the pipe has no data. One worker preserves partial records across consumer timeouts; its queue is limited to 256 packets and 64 MiB of packet payload. The parser can retain one additional packet of up to 16 MiB while waiting for that budget. EOF is published after queued packets drain. Stop wakes both IO and queue waits, joins the worker, and leaves caller-owned IO open.
+
+IP reassembly exposes a logical packet through `meta[:reassembled_packet]`. TCP analysis exposes fields and logical protocol details, but no stable complete TCP byte-buffer API is used. Logical fields are labeled reassembled and do not point into unrelated original-frame bytes. Separate reassembled byte tabs await a supported upstream contract.
+
+Helper stdout contains pcapng only; stderr contains versioned JSONL hello, started, stats, warning, error, and stopped events. SIGTERM and parent stdin EOF request orderly termination; signal handlers only change flags. Privileged launch checks root-owned wrappers and ancestors, uses argument arrays, and strips Ruby startup/dependency injection from inherited environment variables.
+
+## Zaniah 0.12
+
+Vanken uses upstream mutable lists, VirtualTable, TreeView, HexView, token completion, validation states, SplitPane, menus/actions, native dialogs, and ProcessPool. No duplicated incubator implementation remains. The upstream ADR and component docs cover resizing, tail following, TUI representation, and accessibility.
+
+Upgrades require contract tests, then the full suite, types, privileged capture, benchmarks, and native smoke. Changes to private packet/session APIs belong inside Gateway.

data/exe/vanken

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vanken"
+exit Vanken::CLI.start(ARGV)

data/exe/vanken-capture

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vanken/capture/helper_main"
+
+exit Vanken::Capture::HelperMain.new.run(ARGV)

data/lib/vanken/app/capture_controller.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../capture/launcher"
+require_relative "../capture/control_protocol"
+require_relative "../gateway/file_reader"
+require_relative "document"
+
+module Vanken
+  module App
+    class CaptureController
+      class Error < Vanken::CaptureError
+        attr_reader :code
+
+        def initialize(message, code: "internal")
+          @code = code
+          super(message)
+        end
+      end
+
+      def initialize(launcher: nil, preferences: nil, on_update: nil, on_document: nil)
+        @preferences, @on_update, @on_document = preferences, on_update, on_document
+        @launcher = launcher || Capture::Launcher.new(strategy: preferences&.get("capture.launcher") || :auto)
+        @mutex = Mutex.new
+        @state, @stats = :idle, {}
+      end
+
+      def state = @mutex.synchronize { @state }
+      def stats = @mutex.synchronize { @stats.dup }
+      def error = @mutex.synchronize { @error }
+      def warning = @mutex.synchronize { @warning }
+      def document = @mutex.synchronize { @document }
+      def options = @mutex.synchronize { @options&.dup }
+      def capturing? = state == :capturing
+      def running? = @mutex.synchronize { !!@worker&.alive? }
+      def snapshot = @mutex.synchronize { {state: @state, stats: @stats.dup, error: @error, warning: @warning, document: @document} }
+
+      def start(options)
+        @mutex.synchronize do
+          raise Error, "capture controller is closed" if @closed
+          raise Error, "capture is already running" if @worker&.alive?
+
+          @options = if options.is_a?(Hash)
+                       defaults = @preferences&.get("capture") || {}
+                       defaults.merge(options.transform_keys(&:to_s)).reject { |key, _| key == "launcher" }
+                     else
+                       options.dup
+                     end
+          @options = if @options.is_a?(Hash)
+                       @options.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+                     else
+                       @options.map { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+                     end
+          @state, @stats, @error, @warning = :starting, {}, nil, nil
+          @stop_requested, @started, @stopped_event, @handle, @stopper = false, false, false, nil, nil
+          @worker = thread { run }
+        end
+        notify
+        self
+      end
+
+      def stop
+        changed = @mutex.synchronize do
+          next false unless @worker&.alive?
+
+          @stop_requested = true
+          @state = :stopping unless @state == :failed
+          stop_helper
+          true
+        end
+        notify if changed
+        self
+      end
+
+      def wait(timeout = nil, **options)
+        timeout = options.fetch(:timeout, timeout)
+        worker = @mutex.synchronize { @worker }
+        !worker || worker.join(timeout) ? self : nil
+      end
+      alias await wait
+
+      def close
+        @mutex.synchronize { @closed = true }
+        stop.wait
+        document&.close
+        self
+      end
+
+      private
+
+      def run
+        handle = @launcher.launch(@options)
+        @mutex.synchronize do
+          @handle = handle
+          stop_helper if @stop_requested
+        end
+        control = thread { consume_control(handle.stderr) }
+        doc = Document.new(preferences: @preferences, on_update: @on_update)
+        @mutex.synchronize { @document = doc }
+        @on_document&.call(doc)
+        reader = Gateway::FileReader.new(handle.stdout)
+        doc.ingest(reader, live: true)
+        doc.wait
+        unless control.join(3)
+          fail_capture(Error.new("capture stdout closed before the helper stopped"))
+          stop
+          control.join
+        end
+        status = handle.wait(timeout: 3) || handle.stop(timeout: 3)
+        raise Error, doc.error.message if doc.error
+        unless @mutex.synchronize { @error || (@started && @stopped_event && status&.success?) }
+          raise Error, "capture helper closed without a stopped message"
+        end
+        completed = true
+      rescue StandardError => error
+        fail_capture(error)
+      ensure
+        if handle
+          @mutex.synchronize { stop_helper } unless handle.status
+          @stopper&.join
+        end
+        control&.join
+        doc&.wait
+        reader&.close unless doc
+        handle&.close
+        @mutex.synchronize do
+          @handle = nil
+          @state = @error || !completed ? :failed : :stopped
+        end
+        notify
+      end
+
+      def consume_control(io)
+        while (line = io.gets(Capture::ControlProtocol::MAX_LINE_BYTES + 1))
+          event = Capture::ControlProtocol.parse(line)
+          next unless event
+
+          case event["type"]
+          when "started"
+            @mutex.synchronize do
+              @started = true
+              @state = :capturing unless @stop_requested || @error
+            end
+          when "stats"
+            @mutex.synchronize { @stats = event.reject { |key, _| %w[v type].include?(key) }.transform_keys(&:to_sym) }
+          when "warning"
+            @mutex.synchronize { @warning = event["message"] }
+          when "error"
+            if event["fatal"] != false
+              fail_capture(Error.new(event["message"].to_s, code: event["code"].to_s), replace: true)
+              stop
+            else
+              @mutex.synchronize { @warning = event["message"] }
+            end
+          when "stopped"
+            @mutex.synchronize do
+              @stopped_event = true
+              @stats = event["stats"].transform_keys(&:to_sym) if event["stats"].is_a?(Hash)
+            end
+          end
+          notify
+        end
+        unless @mutex.synchronize { @stopped_event || @error }
+          fail_capture(Error.new("capture control channel closed without a stopped message"))
+          stop
+        end
+      end
+
+      # Called under @mutex; the helper stop runs separately so UI callbacks never wait for it.
+      def stop_helper
+        return unless @handle && !@stopper
+
+        handle = @handle
+        @stopper = thread { handle.stop(timeout: 3) }
+      end
+
+      def fail_capture(error, replace: false)
+        @mutex.synchronize do
+          @error = error.is_a?(Error) ? error : Error.new(error.message) if replace || !@error
+          @state = :failed
+        end
+        notify
+      end
+
+      def thread(&block)
+        Thread.new do
+          Thread.current.report_on_exception = false
+          block.call
+        rescue StandardError => error
+          fail_capture(error)
+        end
+      end
+
+      def notify = @on_update&.call(self)
+    end
+  end
+end