spike(pdf): PDF route decision for T8

[wiggdevin]

spike(pdf): PDF route decision for T8

Summary

Throwaway spike per T8. Renders one real Broken English document (an approval
page from brand/render-approval.py, with a table, a code block, a remote
image, and enough text for three pages) through route (b), one Rust
HTML-to-PDF crate (headless_chrome print-to-pdf), and picks that route for
T9. Route (a) — a webview print-to-PDF Tauri command — was disqualified by
reading the pinned wry 0.55.1 source: createPDFWithConfiguration is
#[cfg(target_os = "ios")]-only, so it does not exist on the desktop targets
this app ships. No production code lands from this branch; the deliverable is
the memo at docs/plans/2026-09-04-pdf-route.md plus the throwaway harness
and validator scripts under scripts/pdf-spike/ and scripts/zs/.

Validation per T8: pdftotext extracts the three headings, the table cells,
and the code line; pdftoppm renders all 3 pages without error; size and wall
time are recorded. The offline case points the fixture's remote image at a
local sentinel HTTP server that logs and refuses every request — the sentinel
log shows the attempt and the PDF shows the placeholder. No firewall rules
were changed.

Fork deviations

• Finding 1 fix: added an explicit "Owner sign-off needed" memo section
  rather than executing route (a) live or building a
  WKWebView.createPDF harness — both are the finding's alternative
  remediation, but building either is itself a scope decision that needs
  Devin's sign-off, the same gap this round is fixing; doing it unasked would
  pre-empt his reject-path choice.
• Finding 6 fix used the cheaper of the finding's two named options (assert
  each fixture's external-reference count) rather than CDP-level request
  interception, matching the finding's own "or" and this ticket's throwaway-
  tooling scope.

Gates

Fast gates (builder, on the pre-rebase branch):

• just fmt-check clippy desktop-check desktop-tauri-fmt-check desktop-tauri-clippy file-size-check — pass
• just desktop-test — pass
• just desktop-tauri-test — pass
• scripts/pdf-spike/validate.sh — exit 0
• scripts/zs/pdf-validate.sh (non-vacuous check: a 1-page PDF fails with 7 FAILs, exit 1) — verified
• just fmt-check — pass
• just file-size-check — pass

Rebase and re-verification (PR opener, this pass):

• git rebase --signoff origin/zs/main — clean, no conflicts
• just ci on the rebased branch — exit 0
• Tree clean after the run (git status --porcelain empty)
• All 6 commits carry a Signed-off-by trailer (one commit carries two,
  from an earlier rebase pass; every commit has at least one)

Tested base OID: 35d4e2c9aa311837365b1708e3e28f870c483c46

Gemini 3.8 Flash tester

{"verdict":"SKIPPED","repro":"docs-only ticket","missing_tests":[],"dirty_files":[],"report_path":""}

Critic

Winner: parity.

Biggest gap: the picked route's only hard dependency is never measured —
it drives a separately-installed Google Chrome, and the memo hands T9 an
unpriced "Chrome may be absent — evaluate the fetch feature" note instead
of a number (no download size, no cold-fetch time, no behaviour on a machine
without Chrome, no bundle cost). It also never raises that Chrome is Blink
while the app's T2 viewer is WebKit, so the exported PDF is rendered by a
different engine than the page the user sees. For a ticket whose whole
deliverable is a route decision, the winning route's decisive shipping cost
is the one number missing.

Checklist: parity true, deviations named true, acceptance met false,
nothing above NIT false.

Notes: reproduced everything from the worktree after
. ./bin/activate-hermit: scripts/pdf-spike/validate.sh exit 0, all 6 PNG
sha256s and both fixture hashes byte-identical to the memo, page count 3,
headings/table cells/code marker extracted, sentinel logged exactly one
refused GET; just fmt-check and just file-size-check pass; all 4 commits
(at review time) signed off; tree clean. Falsified the online gate directly
(img → 127.0.0.1:1 gives image_state=failed and exactly 110,006 bytes as
claimed) and proved scripts/zs/pdf-validate.sh is non-vacuous (1-page PDF →
7 FAILs, exit 1). Route (a)'s disqualification is verified against pinned
wry 0.55.1 source, including that createPDFWithConfiguration is
#[cfg(target_os = "ios")]-only.

acceptance_met false: the ticket says render through (a) AND (b); route (a)
produced no artifact, no page, no hash, no wall time — it was decided, not
measured, and the fixture is synthetic rather than the real approval page
(both deviations are named in the memo).

nothing_above_nit false: three WARNs open — no route-(a) render; unmeasured
Chrome dependency plus unmentioned Blink/WebKit divergence; and the landed
spike Cargo manifest is Renovate-visible (config:recommended,
automerge: true, cargo manager, no ignorePaths) so it will attract
auto-merging bumps on zs/main forever.

Full reasoning:
/private/tmp/claude-501/-Users-zero-suminc-/a0fab389-7ac7-4f57-88e6-599d452e8e3a/scratchpad/wave1/spike-pdf/critic.md;
blind pair at critic-A (memo) and critic-B (ticket text).

GPT-5.6 Sol audit

Sol ran. Verdict: BLOCK — 3 blockers and 3 warnings, recalibrated by the
driver against the code to 0 BLOCK, 4 WARN, 2 NIT (every BLOCK either
contradicted the ticket text or was already covered at WARN by a real but
non-critical defect).

Report: /private/tmp/claude-501/-Users-zero-suminc-/a0fab389-7ac7-4f57-88e6-599d452e8e3a/scratchpad/wave1/spike-pdf/audit.md

Verified findings:

1. WARN — scripts/pdf-spike/validate.sh:77 — check_external_reference_count
   uses grep -cE, which counts matching lines, not occurrences.
   Reproduced: a line holding both the sentinel <img> and a second
   https:// reference returns 1, so the offline fixture's expected count of
   1 still PASSes while Chrome (launched with unrestricted networking)
   fetches the extra resource. The memo asserts the property the check lacks
   (docs/plans/2026-09-04-pdf-route.md:452: "A later fixture edit that adds
   any other external reference now fails this check"). No leak exists today
   — all four fixtures verified lines==occurrences. Recalibrated from Sol's
   BLOCK: T8 prescribes the local sentinel and forbids firewall changes, so
   this is a broken static check plus a memo overclaim, not a missing egress
   boundary.
   Fix: count occurrences
   (got=$(grep -oE '...' "$fixture" | wc -l | tr -d ' ')), and add a
   two-references-on-one-line control fixture the check must reject — or
   soften the memo claim to what the check actually enforces.

2. WARN — scripts/pdf-spike/validate.sh:278 —
   run_offline_negative_control re-implements the image_state comparison
   instead of calling the production gate at validate.sh:196. Loosen :196
   back to != "loaded" and the suite stays green: the offline run reports
   failed (passes the loosened gate) and the control reports missing (its
   own independent branch still PASSes). Nothing else reads image_state for
   offline mode. This is AGENTS.md Review-Proven Rule 3 — a guard whose
   loosening fails no check protects nothing — and both the memo (:437-441)
   and the script comment (validate.sh:270-277) claim the control proves
   the run_offline gate would reject the broken-instrumentation case, which
   it does not.
   Fix: extract one require_offline_image_failure <state> helper, call it
   from run_offline, and have the negative control assert that same
   function rejects missing (add timeout and loaded cases too).

3. WARN — docs/plans/2026-09-04-pdf-route.md:337 — the memo's three
   "committed" measurement rows and both committed PDF hashes contradict the
   committed evidence log the memo cites. Memo: online 4719/27/195 ms sha
   2a6c997f, offline 3937/21/189 ms sha 6e6e7cd3, negative 3901/65/183 ms.
   scripts/pdf-spike/out/validate.log: 3501/38/176 sha 6c057e5b,
   3384/87/154 sha f721364c, 3400/40/175. Byte counts and all six PNG
   hashes DO match, so the memo was only partially refreshed after a re-run.
   The memo's own PDF-nondeterminism note explains a differing hash but not
   differing timings both labelled "committed". The pick does not depend on
   these numbers; the defect is evidence integrity in the deliverable.
   Fix: regenerate the three committed rows and both PDF sha256 values from
   out/validate.log, or retain and name the separate run artifact that
   produced the memo's numbers.

4. WARN — docs/plans/2026-09-04-pdf-route.md:8 — landing gate, not a
   code defect: the route pick rests on two scope deviations from T8 the
   owner has not accepted — a synthetic fixture instead of the real
   brand/render-approval.py page (deviation 1), and route (a) never
   executed, disqualified by reading pinned wry 0.55.1 source rather than
   by measurement (deviation 3). The memo discloses both openly ("Owner
   sign-off status: pending" at :8, explicit accept/reject with consequences
   at :477-511), so nothing is hidden and no code edit resolves it. Sol's
   third sub-claim — that the ticket required actual outbound-network
   blocking — is dropped: T8 prescribes the local sentinel and states "No
   firewall rules are changed."
   Fix: do not land this branch or start T9 until Devin's explicit
   accept/reject of deviations 1 and 3 is recorded in the PR body, per the
   implementation plan's loop step 3. Recorded here: pending Devin's
   accept/reject — see this PR's description above for both deviations.

5. NIT — scripts/pdf-spike/src/sentinel.rs:83 — Err(_) => continue in
   the listener.incoming() loop swallows every accept failure with no
   diagnostic, no backoff and no terminal state — the shape Review-Proven
   Rules 1 and 4 name. Downgraded from Sol's WARN because it cannot produce a
   false PASS: the sentinel is killed by cleanup_sentinel after each
   render, so any spin is bounded by one render, and if accept never
   succeeds the log carries no nonce-bearing GET and validate.sh:184 fails
   the run. Failure direction is safe; the diagnostic is poor.
   Fix: log the error and exit nonzero on the first accept failure, or bound
   retries with backoff and a terminal error.

6. NIT — scripts/pdf-spike/validate.sh:356 —
   fixtures/remote-image.png (sha256 c4e870d3) is called "hash-pinned"
   three times in the memo (:81, :268, :272) but nothing in validate.sh or
   scripts/zs/pdf-validate.sh asserts its digest — the digest appears only
   in the memo. A different noisy 800x600 PNG over 300 KB passes
   image_state=loaded, the pdfimages 800x600 check, the 300,000-byte
   floor and the external-reference check while the memo keeps citing the
   original digest. NIT rather than Sol's WARN: the digest is recorded so a
   reviewer can check by hand, and the dimension and size floors bound the
   substitution loosely.
   Fix: assert the exact sha256 of fixtures/remote-image.png before
   rendering (shasum -a 256 -c), plus a control proving a same-dimension
   replacement fails.

Discarded (Sol claims not carried forward):

• Sol finding 1 sub-claim (branch substituted a sentinel for the "actual
  outbound-network blocking" T8 required) — contradicted by the ticket text:
  T8 says to point the fixture's remote image at a local sentinel HTTP
  server that logs and refuses every request, with no firewall rules
  changed. The branch implements exactly that. The unapproved-deviations
  half of the finding survives as WARN 4.
• Sol finding 2 sub-claim (offline behaviour must be enforced at the browser
  seam via CDP request interception because a regex check is not an egress
  boundary) — same ticket text: the harness was never asked to be an egress
  boundary, and firewall changes are explicitly forbidden. The underlying
  counting bug (reproduced against a two-URL line) is real and kept as
  WARN 1, at WARN rather than BLOCK.
• Sol finding 3 (BLOCK severity for the non-binding offline negative
  control) — the defect is real and kept as WARN 2, recalibrated to WARN: no
  production code lands from this throwaway branch, and the committed run
  does exhibit the intended failed/missing split
  (out/validate.log lines 36 and 80). The exposure is a future edit of a
  spike harness plus a false claim in the memo, not a live wrong result.

Test plan

• scripts/pdf-spike/validate.sh exits 0 against the committed fixture
  set (online, offline, negative-control cases)
• pdftotext extracts the three headings, the table cells and the code
  line from the route-(b) output
• pdftoppm renders all 3 pages without error for the route-(b) output
• Sentinel log shows exactly one refused GET for the offline case; PDF
  shows the placeholder image
• scripts/zs/pdf-validate.sh proven non-vacuous (1-page PDF input →
  7 FAILs, exit 1)
• just fmt-check clippy desktop-check desktop-tauri-fmt-check desktop-tauri-clippy file-size-check, just desktop-test,
  just desktop-tauri-test — pass (fast gates)
• just ci on the rebased branch — pass (exit 0)
• Route (a) rendered and measured (open — see Critic and Sol WARN 4;
  pending Devin's accept/reject of the memo's deviations)

🤖 Generated with Claude Code

https://claude.ai/code/session_01E51uwemNnQ6wdrBWU9EhPE

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}