Feature: --checksum — emit SHA-256 hash of result set

[vmvarela]

Context

No competitor offers a result-set checksum for pipeline reproducibility. In CI/CD data pipelines, checking whether query output changed between commits typically requires fragile text diffing. A SHA-256 checksum of the result set provides a deterministic, format-agnostic fingerprint.

Proposed flag

--checksum         Print SHA-256 hash of the result set to stderr before results

UX examples

# Check if query output changed between commits
sql-pipe data.csv --checksum "SELECT * FROM data ORDER BY id" > /dev/null
# stderr: # checksum: d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592

# In CI: diff the checksum
git stash && sql-pipe data.csv --checksum "SELECT * FROM data" >/dev/null 2>new.hash
git stash pop && diff old.hash new.hash

Scope (v1)

• Hash is emitted to stderr as a comment line: # checksum: <hex>
• Hash is computed on the formatted output bytes (after the chosen output format is applied), so --json and --csv of the same data produce different hashes — intentional; hash identifies "this exact output"
• Uses std.crypto.hash.sha2.Sha256 (already in zig stdlib, zero deps)
• Works with all output formats
• Hash is computed last (after all rows are written), printed to stderr before exit

Excluded (YAGNI)

• --checksum-col <name> adding a hash column to output (breaks schema; use stderr sidecar)
• Row-level hash / Merkle tree (use SQL)
• Multiple hash algorithms (MD5, SHA-512)
• Hash verification mode (--verify-hash) — diff the hashes externally
• Hashing individual columns
• Deterministic sort enforcement (user must ORDER BY if needed)

Files affected

• src/args.zig — parse --checksum flag
• src/main.zig — wrap output writer with a hashing writer, emit hash to stderr after query
• No new file needed — hash computation is a few lines

Acceptance criteria

• Same input + same query + same output format = same hash (deterministic)
• Different output produces different hash
• Hash printed to stderr, not stdout (does not pollute piped output)
• Format: # checksum: <64-char hex> (machine-parseable)
• Works with --json, --csv, --table, --markdown, etc.
• Integration test: capture stderr, verify hash matches expected value for known fixture