fix(cli,storage,forms): complete CSV escape + TOCTOU + zip leak + exempt-offerings num (sec)

[sroussey]

Summary

Bundles three independently-rooted correctness fixes — one CRITICAL CLI hardening, one HIGH-severity storage TOCTOU + a HIGH-severity disk leak, and one HIGH-severity data-correctness bug in the exempt-offerings extractors. All seven commits land on claude/wonderful-hypatia-gdhUE; the full suite (bun test) passes 845/845.

Plan F — Complete CSV escape hardening (CRITICAL)

src/cli/output/TableRenderer.ts was vulnerable to CSV / spreadsheet-formula injection via three bypasses on top of PR #119's line-by-line defusing:

• Tighten LEADING_WS: only strip space-like characters spreadsheets silently ignore (ASCII space, NBSP, SHY, ZWSP, ZWNJ, ZWJ, LRM, RLM, BOM). \t and \r are themselves dangerous formula leads, so we no longer strip them before the DANGEROUS_LEAD check; otherwise "\t=cmd" or "\r=cmd" slipped through as non-dangerous after the strip.
• Bare-CR split: change value.split(/(\r?\n)/) → value.split(/(\r\n|\r|\n)/) so a bare CR inside a multi-line cell is also a line boundary; the line after the CR is independently defused.

Tests in src/cli/output/TableRenderer.test.ts now cover all 7 zero-width prefixes + the bare-CR scenarios + a ZWSP-then-benign negative control. 44/44 cases pass.

Plan G — TOCTOU PK race + bootstrap zip leak (HIGH × 2)

• New src/util/AsyncMutex.ts: trivial promise-queue mutex with rejection-isolated chaining so one failing critical section doesn't poison subsequent calls.
• PersonObservationRepo / CompanyObservationRepo upsertByNaturalKey: wrap the INSERT branch in a process-wide static AsyncMutex and re-check the natural key inside the critical section. Without the fix, two concurrent inserts on an empty in-memory store both observed size() as 0 and assigned observation_id = 1 to two different natural keys. Update-of-existing rows remain lock-free.
• BootstrapDownloadTask: wrap the Bun.spawn(unzip) + exit-code check in try { ... } finally { rmSync(zipPath, { force: true }); }. The multi-GB staged zip used to leak whenever Bun.spawn threw or unzip exited non-zero; now it's removed on every exit path.

New tests:

• PersonObservationRepo.test.ts / CompanyObservationRepo.test.ts: concurrent INSERT-on-empty must yield distinct sequential ids; concurrent UPDATE-existing + parallel INSERT must keep the original id stable.
• BootstrapDownloadTask.test.ts gains an "execute zip cleanup" describe block: stubs fetch + Bun.spawn + Bun.which, asserts zip removed on (a) spawn-throws, (b) unzip-exits-nonzero, (c) success.

Plan H — Exempt-offerings num() bug (HIGH × 1, broad scope)

The four exempt-offering schemas (Form 1-A, 1-K, 1-Z, C) typed every decimal XML leaf as Type.Number(). When EDGAR shipped an empty or whitespace-only element, Value.Convert on Type.Number() silently coerced it to 0, which then propagated through RegAOfferingHistory, RegAFinancialData, CrowdfundingOfferings, and CrowdfundingReports as a legitimate-looking zero-dollar amount.

• New src/sec/forms/_valueHelpers.ts with strScalar / numScalar / strWrapped / numWrapped. numScalar treats empty / whitespace-only / NaN / Infinity input as null and rejects thousand-separator strings; legitimate "0" round-trips. Inline copy of the helpers PR fix(forms,storage): Form 144 num() whitespace + PG bulk-writer duplicate-CIK dedup #118 introduced under src/sec/forms/insider-trading/_valueHelpers.ts — when fix(forms,storage): Form 144 num() whitespace + PG bulk-writer duplicate-CIK dedup #118 merges, the duplicate should be reconciled to a single shared module.
• Schemas: change DECIMAL_TYPE* aliases from Type.Number() to Type.String() in all four schemas (1-A: 4 aliases, 1-K: 2, 1-Z: 2, C: 4). Type.Integer() aliases stay untouched.
• Storage: wrap every numeric field read with numScalar(...) in Form_1_A.storage.ts (processFinancialData, processForm1A history build), Form_1_K.storage.ts (processOfferingHistory), Form_1_Z.storage.ts (processOfferingSummaries, processCertificationSuspension.approxRecordHolders), and Form_C.storage.ts (processOfferingInfo, processAnnualReportDisclosures). extractor_version bumped 1.0.0 → 1.1.0 in all four with the standard re-extract comment.
• Tests: parsing assertions updated for the new string contract (decimals are raw XML text, integers stay numbers). New storage regression tests in each *.storage.test.ts cover null / empty / "0" round-trip.

Plan H is intentionally split across 5 commits (parts 1/5–5/5) due to the push-files tool size limit; the diffs taken together are exactly one Plan H.

Findings closed

• CRITICAL: CSV formula-injection in TableRenderer.escapeCsvValue (3 follow-up failing cases on top of fix(cli): harden CSV formula-injection escape (sec) #119: \t/\r leads, bare-CR multi-line lines, zero-width-prefix bypasses).
• HIGH: TOCTOU race on synthetic observation_id in PersonObservationRepo and CompanyObservationRepo.
• HIGH: Bootstrap-download zip leak — staged multi-GB archives leaked on Bun.spawn failure or non-zero unzip exit.
• HIGH: Empty/whitespace numerics in exempt-offering filings persisted as fabricated 0 in offering history, financial data, and crowdfunding disclosures.

Reconciliation with open PRs

This PR shares scope with #118 (insider-trading _valueHelpers) and #119 (CSV escape line-by-line defusing). Neither is closed by this PR — they should be reconciled at merge time:

• fix(forms,storage): Form 144 num() whitespace + PG bulk-writer duplicate-CIK dedup #118 introduces src/sec/forms/insider-trading/_valueHelpers.ts. This PR adds an inline copy at src/sec/forms/_valueHelpers.ts and uses it from the exempt-offering storage extractors. When fix(forms,storage): Form 144 num() whitespace + PG bulk-writer duplicate-CIK dedup #118 lands, the duplicate copy here should be removed and the imports rewritten to point at the shared module (probably promoted to src/sec/forms/_valueHelpers.ts once both branches merge).
• fix(cli): harden CSV formula-injection escape (sec) #119 introduces the line-by-line defusing in TableRenderer.escapeCsvValue. Plan F layers two refinements on top — tightened LEADING_WS and \r\n | \r | \n split. The merge should preserve the fix(cli): harden CSV formula-injection escape (sec) #119 base structure and apply the Plan F deltas.

Test plan

• bun test src/cli/output/TableRenderer.test.ts — 44 cases pass.
• bun test src/storage/observation — Person+Company repo tests pass, including new TOCTOU regression cases.
• bun test src/task/bootstrap — streamDownloadToFile cases plus new zip-cleanup cases pass.
• bun test src/sec/forms/_valueHelpers.test.ts — 32/32 helper unit tests pass.
• bun test src/sec/forms/exempt-offerings — 195/195 parse + storage tests pass, including new null/empty/"0" regression guards per form.
• bun test whole-suite — 845/845.

https://claude.ai/code/session_01Wws8oZpB5imjKL2e7DRXtc

---

Generated by Claude Code