docs: integrity & robustness audit (May 2026)#96
Merged
Conversation
2 tasks
Exelord
pushed a commit
that referenced
this pull request
May 16, 2026
Captures what each runner does at each step of a `vx run` invocation. Companion to the integrity-audit doc (PR #96): that one is "what's wrong", this one is "what's everyone doing". Structure: - Quick-scan summary table (14 phases × 3 runners) - Per-phase deep dives (14 sections, each with its own table + callout for where we have a gap vs Turbo/Nx) - Cross-links to comparison.md (feature backlog) and the integrity audit (correctness backlog) Sources pinned to revisions: - Turbo: /tmp/turbo at 71f8c90 - Nx: /tmp/nx at 962f146 - vx: main Daemon paths in Nx deliberately excluded — we're daemonless by design. This is reference / context, not a backlog. When `main` moves, the vx column moves with it.
Exelord
pushed a commit
that referenced
this pull request
May 17, 2026
PR #100's CI failed on format-check because the new docs (patterns.md, benchmarks.md) used inconsistent column padding in markdown tables. PR #96 / #97's monorepo-structure.md regressed the same way. `bun src/bin.ts run format` rewrites all three to oxfmt's canonical table alignment. No content changes.
Exelord
pushed a commit
that referenced
this pull request
May 17, 2026
Captures what each runner does at each step of a `vx run` invocation. Companion to the integrity-audit doc (PR #96): that one is "what's wrong", this one is "what's everyone doing". Structure: - Quick-scan summary table (14 phases × 3 runners) - Per-phase deep dives (14 sections, each with its own table + callout for where we have a gap vs Turbo/Nx) - Cross-links to comparison.md (feature backlog) and the integrity audit (correctness backlog) Sources pinned to revisions: - Turbo: /tmp/turbo at 71f8c90 - Nx: /tmp/nx at 962f146 - vx: main Daemon paths in Nx deliberately excluded — we're daemonless by design. This is reference / context, not a backlog. When `main` moves, the vx column moves with it.
Captures findings from a Turbo + Nx code review focused on the correctness / robustness dimensions we hadn't systematically checked. Six concrete gaps, each with a verified source link in either repo and a fix sketch. Ordered by severity × ease so we can ship the small-but-high-value ones first. Headline gaps: 1. No SIGINT/SIGTERM handler in run() — Ctrl+C orphans child tasks + skips cache.close() (Nx forwards signals via IPC). 2. Path-traversal hole in extractOutputs — a malicious tar entry name with `../` would escape destDir (Turbo gates this via lexical canonicalization in the symlink restore path). 3. No content verification on restore — bit-flips, partial writes, manual tampering all silent. Cheap fix: xxh3(compressed_bytes) stored in entries row. 4. No HMAC on remote artifacts — Turbo gates this behind TURBO_REMOTE_CACHE_SIGNATURE_KEY; we don't have an equivalent. 5. No machine-ID gate — Nx hashes machine GUID into entries to reject cross-OS restores. Only matters for shared <cacheDir>. 6. No retry on transient FS failures — Nx wraps FS ops in exponential backoff (Math.random()*2+2 base exponent, 6 attempts max). Recommended ship order: items 1–4 as small focused PRs; 5–6 deferred until a user actually runs into shared-cache or flaky-FS scenarios. Document records the threat model + Turbo/Nx source references so future agents have the context. Also documents what we already cover (PRs #88, #91, #92, #95) and what we explicitly won't ship (TUI mode selection, flake tracking, per-task .env hashing) to keep this doc as a single source of truth for the integrity backlog.
Exelord
force-pushed
the
claude/integrity-audit-doc
branch
from
ae68a33 to
1a94699
Compare
Exelord
pushed a commit
that referenced
this pull request
May 17, 2026
PR #100's CI failed on format-check because the new docs (patterns.md, benchmarks.md) used inconsistent column padding in markdown tables. PR #96 / #97's monorepo-structure.md regressed the same way. `bun src/bin.ts run format` rewrites all three to oxfmt's canonical table alignment. No content changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Captures findings from a Turbo + Nx code review focused on correctness / robustness gaps the recent speed work didn't surface. Six concrete items, each with a verified source link in either repo and a fix sketch.
Gaps documented, ranked by severity × ease
run()extractOutputsentries.artifact_hash)entries.machine_id)Items 1–4 are small focused PRs that should land soon. 5–6 are env-gated features that should land only when a user drives the requirement.
What's also recorded
Each finding cites the exact file:line in Turbo / Nx so the next agent looking at this can verify the claims rather than re-discover them. Filtered out the false positives from the Explore subagents (both confidently reported things we'd already shipped).
File
docs/design/integrity-audit-2026-05.md(313 lines)Test plan
bun src/bin.ts run formatcleanWhat's next
If you agree with the ranking, I'll open follow-up PRs in the documented order. Item 1 (SIGINT handler) is genuinely a high-severity easy fix and is the natural next merge.
https://claude.ai/code/session_016HXj6HW6bxSn8EYuKcxTD9
Generated by Claude Code