diff --git a/.env.example b/.env.example
index 377ae3d..89be357 100644
--- a/.env.example
+++ b/.env.example
@@ -45,7 +45,8 @@ PREVIEW_ROW_LIMIT=25
 FLATTEN_MAX_DEPTH=10
 
 # XLSX-only export budget, in cells (rows x columns). Derived from the
-# measurement in docs/export-budget-v1.2.md. CSV/TSV are streamed and uncapped.
+# measurement in docs/plan-status-v1.2.md, Appendix A. CSV/TSV are streamed and
+# uncapped.
 # 0 disables the guard.
 MAX_EXPORT_CELLS=250000
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 64ec424..693b9d8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,9 +7,10 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [1.2.0] - 2026-08-21 — "Hardening & Performance"
 
-Implements `docs/roadmap-v1.2.md`, closing every finding in
-`docs/security-review-v1.2.md` (F1–F17) and `docs/performance-review-v1.2.md`
-(P1–P13).
+Implements the v1.2 roadmap, closing every security finding (F1–F17) and
+performance finding (P1–P13). Those four planning documents were later
+consolidated into `docs/plan-status-v1.2.md`; their full text remains in git
+history at `065883f`.
 
 No response key changed name, type or meaning; `/process` only gained keys.
 
@@ -68,7 +69,7 @@ No response key changed name, type or meaning; `/process` only gained keys.
 - **Diskless, memory-bounded exports (P3).** CSV/TSV are generator-streamed and
   uncapped. XLSX keeps a normal-mode workbook (no OS temp files) plus
   `MAX_EXPORT_CELLS`, measured rather than guessed — see
-  `docs/export-budget-v1.2.md`.
+  `docs/plan-status-v1.2.md`, Appendix A.
 - **Lazy tree picker (P4)** and **client render caps (P5)**: children build on
   first toggle; nested objects stop at 20 keys, primitive arrays at 20 items,
   strings at 500 characters.
diff --git a/CLAUDE.md b/CLAUDE.md
index 450ade2..8b3a583 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,11 +36,9 @@ json-table-tool/
 │       ├── test_render_caps.mjs
 │       └── test_features.mjs
 ├── docs/
-│   ├── code-health-final.md
-│   ├── security-review-v1.2.md
-│   ├── performance-review-v1.2.md
-│   ├── roadmap-v1.2.md
-│   └── export-budget-v1.2.md   # How MAX_EXPORT_CELLS was measured
+│   └── plan-status-v1.2.md     # The planning doc: what shipped, what is pending,
+│                               # the export-budget measurement (App. A) and the
+│                               # perf budget + RSS protocol (App. B)
 ├── .github/workflows/ci.yml    # lint, format, tests, JS assertions, pip-audit
 ├── pyproject.toml       # ruff + pytest configuration
 ├── requirements.txt     # Runtime dependencies (exact-pinned)
@@ -317,7 +315,7 @@ convention is a dedicated bump commit, not a bump ridden along with a feature.
 
 ### Re-deriving the Excel export budget
 `MAX_EXPORT_CELLS` is a measured number, not a chosen one. Follow the method in
-`docs/export-budget-v1.2.md` (fresh process per measured request, `ru_maxrss`
-converted for the platform, delta across two runs), re-fit against the narrowest
-aspect ratio you care about, and re-run a confirming point at the value you
-intend to ship. Record the new data in that file.
+`docs/plan-status-v1.2.md` Appendix A (fresh process per measured request,
+`ru_maxrss` converted for the platform, delta across two runs), re-fit against
+the narrowest aspect ratio you care about, and re-run a confirming point at the
+value you intend to ship. Record the new data in that appendix.
diff --git a/MEMORY.md b/MEMORY.md
index 8e1154c..83c6607 100644
--- a/MEMORY.md
+++ b/MEMORY.md
@@ -154,7 +154,7 @@ Keep entries short — if it grows past ~10 lines, it probably belongs in `READM
 ### 2026-08-21 — The XLSX export budget is measured, in cells, and on by default  (area: performance)
 
 **What:** `MAX_EXPORT_CELLS` (default 250,000) caps Excel exports only. CSV/TSV are generator-streamed and stay uncapped.
-**Why:** openpyxl memory tracks `rows × columns`, not rows — at equal cell counts a narrow, tall sheet costs *more* (84.3 MiB at 50k×3 vs 73.6 at 15k×10), so a row limit says almost nothing about the footprint. The default comes from the measurement in `docs/export-budget-v1.2.md`, not from feel. An unlimited default would leave a High finding unmitigated; uncapped CSV/TSV is what keeps the export contract as wide as the input contract.
+**Why:** openpyxl memory tracks `rows × columns`, not rows — at equal cell counts a narrow, tall sheet costs *more* (84.3 MiB at 50k×3 vs 73.6 at 15k×10), so a row limit says almost nothing about the footprint. The default comes from the measurement in `docs/plan-status-v1.2.md` (Appendix A), not from feel. An unlimited default would leave a High finding unmitigated; uncapped CSV/TSV is what keeps the export contract as wide as the input contract.
 **How to apply:** Re-derive the number whenever the measurement is re-run — do not round it to something tidy. Never truncate an oversized export: `/process` advertises `total_cells`/`max_export_cells` so the client greys Excel out beforehand, and `/export-xlsx` returns 400 for direct callers. And keep exports diskless: openpyxl's `write_only` mode writes worksheet parts to OS temp files, and `SpooledTemporaryFile` is either pointless (its default `max_size=0` never rolls over) or disk-backed.
 
 **Owner / source:** performance review P3, decision D6.
diff --git a/README.md b/README.md
index eccfb76..6a9ca1d 100644
--- a/README.md
+++ b/README.md
@@ -559,7 +559,7 @@ need no server round trip and nothing is persisted — responses over
 `GZIP_MIN_SIZE` are gzipped to keep that affordable. The preview rows are a
 truncated *copy*, so exports keep full fidelity. Excel exports are bounded by
 `MAX_EXPORT_CELLS`, measured rather than guessed
-(`docs/export-budget-v1.2.md`); CSV and TSV stream and stay uncapped. The JSON
+(`docs/plan-status-v1.2.md`, Appendix A); CSV and TSV stream and stay uncapped. The JSON
 tree picker builds children only when a node is opened.
 
 ---
diff --git a/config.py b/config.py
index 32d3562..30002d7 100644
--- a/config.py
+++ b/config.py
@@ -5,8 +5,8 @@
 # Publicly known, and therefore only ever acceptable outside production.
 DEV_SECRET_KEY = 'dev-secret-key-change-in-production'
 
-# See MAX_EXPORT_CELLS below and docs/export-budget-v1.2.md for how this number
-# was measured.
+# See MAX_EXPORT_CELLS below and docs/plan-status-v1.2.md (Appendix A) for how
+# this number was measured.
 DEFAULT_MAX_EXPORT_CELLS = 250_000
 
 
@@ -164,9 +164,9 @@ class Config:
     # 500 columns have wildly different footprints at the same row count.
     #
     # Enabled by default: an unlimited default would leave P3 (High) unmitigated.
-    # The value is derived from the Performance Review section 4 measurement (see
-    # docs/export-budget-v1.2.md), not chosen by feel -- re-derive it whenever that
-    # measurement is re-run. 0 disables the guard for operators who knowingly opt
+    # The value is derived from the measurement in docs/plan-status-v1.2.md
+    # (Appendix A), not chosen by feel -- re-derive it whenever that measurement
+    # is re-run. 0 disables the guard for operators who knowingly opt
     # out. CSV/TSV stay uncapped and streamed, so every dataset /process accepts
     # remains exportable by some route.
     MAX_EXPORT_CELLS = env_int('MAX_EXPORT_CELLS', DEFAULT_MAX_EXPORT_CELLS)
diff --git a/docs/code-health-final.md b/docs/code-health-final.md
deleted file mode 100644
index 6c854d0..0000000
--- a/docs/code-health-final.md
+++ /dev/null
@@ -1,695 +0,0 @@
-# Code-Health Review — JSON Table Converter
-
-**Date:** 2026-05-02  
-**Reviewer:** Automated senior code-health review  
-**Repository:** https://github.com/Badry-Kudu/json-table-tool  
-**Revision reviewed:** `main` branch (HEAD at time of review)
-
----
-
-## 1. Initial Score Estimate
-
-| Category | Score | Weight |
-|---|---|---|
-| Maintainability | 7/10 | 10% |
-| Test coverage & quality | 8/10 | 15% |
-| Complexity | 7/10 | 10% |
-| Duplication | 8/10 | 5% |
-| Architecture consistency | 8/10 | 10% |
-| Dependency / security risk | 3/10 | 15% |
-| Documentation | 7/10 | 10% |
-| CI/CD reliability | 0/10 | 15% |
-| Input validation & error handling | 9/10 | 10% |
-| Usability & developer experience | 7/10 | 10% |
-
-**Overall weighted score: ~68 / 100**
-
-**Target score: 85+ / 100**
-
----
-
-## 2. Project Overview (Verified)
-
-**Stack:** Python 3.11+, Flask 3.0.0 (app-factory pattern), Flask-WTF (CSRF), Flask-Limiter, gunicorn, requests, openpyxl. Frontend: Vanilla HTML / CSS / JS (no framework, no build step). Tests: pytest.
-
-**Purpose:** Lightweight stateless web tool that converts JSON and JSONL data into viewable HTML tables, with CSV, TSV, and Excel export. Supports file upload, paste, and external API fetch with auth.
-
-**Directory layout:**
-```
-app.py          Flask app factory
-config.py       All settings via env vars
-extensions.py   Shared CSRF + limiter instances
-security.py     SSRF validation + security headers
-helpers.py      Data parsing, flattening, path selection
-routes.py       Blueprint with /, /health, /process, /export-csv, /export-xlsx
-static/         css/style.css  js/app.js
-templates/      index.html (structure only, no inline scripts/styles)
-tests/          conftest.py, test_helpers.py, test_routes.py, test_security.py
-render.yaml     Render.com deployment blueprint
-requirements.txt
-```
-
----
-
-## 3. Commands Run & Results
-
-### Install
-```bash
-pip install -r requirements.txt
-# → Success. All 7 direct dependencies installed.
-```
-
-### Tests
-```bash
-python -m pytest tests/ -v
-# → 82 passed, 2 warnings (openpyxl DeprecationWarning from library internals), 0 failures
-```
-
-### Coverage
-```bash
-coverage run -m pytest tests/ && coverage report -m
-```
-
-| File | Stmts | Miss | Cover |
-|---|---|---|---|
-| app.py | 16 | 1 | 94% |
-| config.py | 14 | 0 | 100% |
-| extensions.py | 5 | 0 | 100% |
-| helpers.py | 78 | 1 | 99% |
-| routes.py | 181 | 33 | 82% |
-| security.py | 33 | 3 | 91% |
-| tests/ | 446 | 0 | 100% |
-| **TOTAL** | **773** | **38** | **95%** |
-
-### Dependency Audit
-```bash
-pip-audit -r requirements.txt
-```
-**Found 7 known vulnerabilities in 4 packages:**
-
-| Package | Current | CVE | Fix Version | Severity |
-|---|---|---|---|---|
-| Flask | 3.0.0 | CVE-2026-27205 | 3.1.3 | — |
-| requests | 2.31.0 | CVE-2024-35195 | 2.32.0 | Medium |
-| requests | 2.31.0 | CVE-2024-47081 | 2.32.4 | Medium |
-| requests | 2.31.0 | CVE-2026-25645 | 2.33.0 | — |
-| gunicorn | 21.2.0 | CVE-2024-1135 | 22.0.0 | High |
-| gunicorn | 21.2.0 | CVE-2024-6827 | 22.0.0 | — |
-| pytest | 7.4.4 | CVE-2025-71176 | 9.0.3 | — |
-
-### Linting / Formatting
-```
-No linting or formatting tools are configured for this project.
-```
-Run (locally or in CI):
-```bash
-pip install ruff
-ruff check .
-ruff format --check .
-```
-
-### Type checking
-```
-No type annotations present. No mypy or pyright configured.
-```
-
-### CI/CD Workflows
-```
-No .github/workflows/ directory found. Zero CI/CD configuration.
-```
-
----
-
-## 4. Category-by-Category Findings
-
-### 4.1 Maintainability — 7/10
-
-**Strengths:**
-- Clean app-factory pattern (`create_app()`) with proper extension initialization.
-- Well-separated modules: `config.py`, `extensions.py`, `security.py`, `helpers.py`, `routes.py`.
-- Consistent docstrings on all public functions.
-- Naming conventions are clear and consistent throughout.
-
-**Issues:**
-- `process_json()` in `routes.py` is ~150 lines with three nested branches (file/paste/api), five auth sub-branches, and a post-parse block — cyclomatic complexity ≈ 15+.
-- No type annotations anywhere. With Flask's dynamic nature, type hints would catch many errors at development time.
-- No linter or formatter configured; code style is consistent now but will drift as contributors add code.
-- `openpyxl` is imported lazily inside `export_xlsx()` — inconsistent with all other imports at module top, and hides ImportError until runtime.
-
-### 4.2 Test Coverage & Quality — 8/10
-
-**Strengths:**
-- **95% overall coverage** — exceptional for a Flask project.
-- 82 tests across three well-organized files (`test_helpers`, `test_routes`, `test_security`).
-- All auth paths tested via mock. SSRF blocking well-covered (16 URL validation tests).
-- Edge cases covered: UTF-8 decoding failure, max-size exceeded, JSONL invalid line, path selection modal flow.
-
-**Issues:**
-- `routes.py` is 82% covered; uncovered lines include auth header/key/bearer/query-param branches (lines 92–109) and the `ValueError` path in `parse_jsonl` when called from API fetch.
-- No edge-case input tests for helpers: `null` values in JSON objects, Unicode / emoji column names, boolean-only arrays, numbers as top-level JSON, empty-object arrays `[{}, {}]`, extremely large number of columns.
-- No test confirming the `PREVIEW_ROW_LIMIT` server config is reflected in the JS badge (hardcoded "25" in `app.js` line 219 and 220 is inconsistent with server config).
-- No test for file upload with no `json_file` field (line 50 branch is untested).
-
-### 4.3 Complexity — 7/10
-
-**Strengths:**
-- `helpers.py` functions are small, single-purpose, and easy to reason about.
-- `security.py` is clear and minimal.
-
-**Issues:**
-- `process_json()` has high cyclomatic complexity and should be refactored: extract `_parse_input(request, data_format)` → returns `(json_data, error_response)` and `_apply_path_selection(json_data, json_path)` → returns `(table_data, error_response)`.
-- `extract_table_data()` falls through multiple isinstance checks with no early return at each branch; a match/case or helper would improve clarity (Python 3.10+).
-- `renderTable` / `renderTableDOM` split in `app.js` is unnecessary — `renderTable` just stores refs then calls `renderTableDOM`, creating indirection without benefit.
-
-### 4.4 Duplication — 8/10
-
-**Strengths:**
-- `escapeHtml()` is defined once and reused across all JS rendering functions — no XSS risk from duplication.
-- `get_all_columns()` is reused for both preview and CSV columns.
-
-**Issues:**
-- `export_csv` and `export_xlsx` both implement identical `dict/list → JSON string` serialization for cell values:
-  ```python
-  if isinstance(v, (dict, list)):
-      clean_row[k] = json.dumps(v)
-  ```
-  This logic should live in a shared helper (e.g., `serialize_cell_value(v)`).
-- `downloadDelimited` in `app.js` and `export_csv` route in `routes.py` both implement CSV serialization independently. This is intentional (client-side fallback + server fallback) but should be documented as such.
-
-### 4.5 Architecture Consistency — 8/10
-
-**Strengths:**
-- Blueprint pattern used correctly. Extensions initialized with `init_app()` pattern.
-- Security headers applied globally via `after_request`. No inline styles/scripts (CSP-safe).
-- Config exclusively from environment variables with documented defaults.
-
-**Issues:**
-- `app = create_app()` at module level in `app.py` (line 28) is fine for `python app.py` dev use, but means importing `app` in tests or tools always creates an app instance with production config. Tests avoid this by calling `create_app()` directly, but it's a subtle trap.
-- `RATE_LIMIT_PROCESS` / `RATE_LIMIT_EXPORT` are stored as custom config keys rather than using Flask-Limiter's standard `RATELIMIT_*` namespace, requiring the lambda wrapper on every route decorator.
-- No `pyproject.toml` or `setup.cfg` — project metadata (name, version, Python constraint) exists only in `config.py` and `render.yaml`, not in a standard packaging file.
-
-### 4.6 Dependency / Security Risk — 3/10
-
-**Strengths:**
-- All direct dependencies are pinned to exact versions — no floating ranges.
-- Minimal dependency footprint: 7 direct deps for a full web app is lean.
-- No unused dependencies found.
-
-**Issues:**
-- **7 CVEs across 4 packages** — all have published fixes:
-  - `gunicorn 21.2.0` → CVE-2024-1135 (HTTP Request Smuggling, **High**) + CVE-2024-6827. Fix: `gunicorn==22.0.0`.
-  - `requests 2.31.0` → 3 CVEs. Fix: `requests==2.33.0` (supersedes all three).
-  - `Flask 3.0.0` → CVE-2026-27205. Fix: `Flask==3.1.3`.
-  - `pytest 7.4.4` → CVE-2025-71176 (test-only, lower risk). Fix: `pytest==9.0.3`.
-- No `requirements-dev.txt` / `requirements-test.txt` separation — `pytest` (test-only) is mixed with production dependencies, meaning it gets installed in production.
-- No transitive dependency pinning (`pip-compile` or lock file). Transitive deps are resolved fresh on every `pip install`, so builds are not fully reproducible.
-- `openpyxl==3.1.2` triggers `DeprecationWarning: datetime.datetime.utcnow()` (library-internal issue, tracked upstream). Fix: upgrade to `openpyxl==3.1.5`.
-
-### 4.7 Documentation — 7/10
-
-**Strengths:**
-- `README.md` is thorough: quick start, full deployment section (Render, gunicorn+systemd+nginx, Docker, Railway, Fly.io), usage guide, security notes, troubleshooting, environment variable table.
-- `CLAUDE.md` provides excellent internal contributor guidance.
-- All Python functions have docstrings.
-
-**Issues:**
-- No `CONTRIBUTING.md` or `DEVELOPMENT.md` — new contributors must infer linting/testing conventions from `CLAUDE.md`.
-- No `CHANGELOG.md` — no history of changes or versioning rationale.
-- No `docs/` directory or architecture decision records.
-- README does not mention linting, type checking, or coverage — the "Development" section only shows `python app.py` and `pytest`.
-- README badge for "License" points to no `LICENSE` file (the file doesn't exist in the repo).
-- Missing: JSON format edge-case examples (null values, booleans, Unicode, deeply nested, large files).
-- `APP_VERSION = '1.1.0'` in `config.py` is not linked to any tag or release — version can drift silently.
-
-### 4.8 CI/CD Reliability — 0/10
-
-**Critical gap.** There is no `.github/workflows/` directory. No CI pipeline exists.
-
-This means:
-- No automated test runs on pull requests or pushes to `main`.
-- Dependency vulnerabilities are never automatically flagged.
-- Linting and formatting checks never run automatically.
-- Regressions can be merged without detection.
-- The `render.yaml` auto-deploys on every push — with no CI gate, broken code deploys directly to production.
-
-**Required:** A GitHub Actions workflow running on `push` and `pull_request` to `main` that:
-1. Installs dependencies
-2. Runs `pytest` with coverage
-3. Runs `ruff check` and `ruff format --check`
-4. Runs `pip-audit`
-
-### 4.9 Input Validation & Error Handling — 9/10
-
-**Strengths:**
-- CSRF protection on all POST routes via Flask-WTF.
-- SSRF protection with DNS validation blocking private/loopback/link-local/multicast IPs.
-- Rate limiting on all routes (configurable).
-- `MAX_CONTENT_LENGTH` enforced (10MB default).
-- API response size capped + streamed (no full-load-then-check).
-- `allow_redirects=False` on API fetch.
-- UTF-8 decoding error caught and returns 400.
-- `UnicodeDecodeError`, `JSONDecodeError`, `ValueError`, `Timeout`, `RequestException` all handled with appropriate HTTP status codes.
-- All `RequestException` detail is swallowed and a generic message returned (no internal host leakage).
-- `escapeHtml()` used consistently in all JS rendering paths (no XSS risk from JSON data).
-
-**Issues:**
-- No JSON parsing depth limit — a specially crafted JSON with 10,000 levels of nesting could exhaust the Python call stack before `flatten_for_csv`'s `max_depth` guard is reached (Python's default recursion limit is ~1000; `json.loads` itself is C-level and handles it, but `extract_table_data` is recursive Python with no depth guard).
-- No file extension validation on upload (any file extension accepted; only content parsing catches non-JSON).
-- No explicit `Content-Type` validation on file upload (`accept=".json,.jsonl"` is client-side only).
-- The JS `formatValue()` function does not guard against extremely large arrays/objects in a cell — rendering a cell with 50,000-item nested array would freeze the browser tab.
-
-### 4.10 Usability & Developer Experience — 7/10
-
-**Strengths:**
-- Drag-and-drop file upload, dark/light theme with `localStorage` persistence, format toggle (JSON/JSONL), multi-format export dropdown.
-- Keyboard-accessible tabs (they are `<button>` elements, not `<div>`, so naturally keyboard-reachable via Tab + Enter).
-- Clear loading/error state management.
-- Path-selector modal for multi-array JSON.
-
-**Issues:**
-- `previewBadge` text "Showing first 25" is hardcoded in `app.js` (lines 219–225) — does not reflect the server-side `PREVIEW_ROW_LIMIT` config. If an operator changes the config to 50, the badge will still say "25".
-- No `.env.example` file — operators must read `README.md` or `config.py` to learn required env vars.
-- No `Makefile` or `justfile` for standard dev commands. `make test`, `make lint`, `make coverage` would lower the contribution friction.
-- `alert()` used for the About dialog (line 477 in `app.js`) — blocks the main thread and is not keyboard dismissible on all browsers in the same way.
-- The export dropdown has no keyboard trigger — `exportBtn` opens/closes the dropdown but the dropdown items are not in the natural Tab focus flow when it is closed.
-- No visual indication when a sort is active after re-submission (sort state is preserved in `sortColumn`/`sortDirection` but the table re-renders without a visual indicator until columns are redrawn).
-- No `LICENSE` file exists despite the README saying MIT.
-
----
-
-## 5. Top 10 Issues Affecting the Score
-
-| # | Issue | Category | Impact | Effort |
-|---|---|---|---|---|
-| 1 | **No CI/CD pipeline** — zero automated checks on PRs or pushes | CI/CD | Critical | Low |
-| 2 | **7 CVEs with published fixes** — gunicorn (HTTP Request Smuggling), requests (3 CVEs), Flask, pytest | Deps/Security | Critical | Low |
-| 3 | **Dev dependencies mixed with production** — `pytest` installed in production | Deps/Security | High | Low |
-| 4 | **No linter or formatter configured** — style drift is inevitable | Maintainability | High | Low |
-| 5 | **`process_json()` is ~150 lines with cyclomatic complexity ≈ 15** | Complexity | Medium | Medium |
-| 6 | **No type annotations** — no static analysis safety net | Maintainability | Medium | Medium |
-| 7 | **Hardcoded "25" in JS badge** inconsistent with server config | Usability/DX | Medium | Low |
-| 8 | **No `LICENSE` file** despite README declaring MIT | Documentation | Medium | Low |
-| 9 | **No `.env.example`** for operator onboarding | DX | Low | Low |
-| 10 | **No JSON depth guard in `extract_table_data()`** — recursive Python with no depth cap | Input Validation | Low | Low |
-
----
-
-## 6. Quick Wins (1–2 hours each)
-
-1. **Bump all vulnerable deps** — update `requirements.txt` to `Flask==3.1.3`, `requests==2.33.0`, `gunicorn==22.0.0`, `openpyxl==3.1.5`, `pytest==9.0.3`.
-2. **Split `requirements.txt`** — create `requirements-dev.txt` for `pytest` (and future `ruff`, `coverage`), keep `requirements.txt` production-only.
-3. **Add GitHub Actions workflow** — basic `ci.yml` that installs, lints, tests, and audits on push/PR to `main`.
-4. **Add `ruff` to dev deps and configure** — add `pyproject.toml` with `[tool.ruff]` section; run `ruff check .` and fix any issues.
-5. **Add `LICENSE` file** — MIT, matching README statement.
-6. **Add `.env.example`** — document all env vars with safe placeholder values.
-7. **Fix hardcoded "25" in `app.js`** — have the server return `preview_limit` in the `/process` response, use it in the badge.
-8. **Extract `serialize_cell_value()` helper** in `routes.py` to remove the duplicated `dict/list → json.dumps` logic.
-
----
-
-## 7. Larger Refactoring Recommendations
-
-### 7.1 Refactor `process_json()` into sub-functions
-Extract three helpers:
-- `_load_from_file(request, data_format) -> tuple[Any, Response | None]`
-- `_load_from_paste(request, data_format) -> tuple[Any, Response | None]`  
-- `_load_from_api(request, data_format, config) -> tuple[Any, Response | None]`
-- `_select_table_data(json_data, json_path) -> tuple[list, Response | None]`
-
-This reduces `process_json` to ~30 lines of orchestration and makes each path independently testable.
-
-### 7.2 Add type annotations
-Add type hints to all function signatures in `helpers.py`, `security.py`, `routes.py`, and `config.py`. Add `mypy` to dev deps and configure it in `pyproject.toml`. Type hints will catch subtle bugs (e.g., `extract_table_data` returning `[]` vs `None`) without changing behavior.
-
-### 7.3 Separate dev and production dependency files
-```
-requirements.txt          # Flask, requests, gunicorn, Flask-WTF, Flask-Limiter, openpyxl
-requirements-dev.txt      # -r requirements.txt + pytest, coverage, ruff, mypy, pip-audit
-```
-This prevents test tooling from being deployed to production.
-
-### 7.4 Add `pyproject.toml`
-Centralizes project metadata, Python version constraint, ruff config, mypy config, and pytest config — replacing scattered `setup.cfg`, `pytest.ini`, or bare `pyproject.toml` fragments.
-
-### 7.5 Add recursion depth guard to `extract_table_data()`
-Add a `_depth=0, max_depth=20` parameter pair matching `flatten_for_csv`'s pattern — prevents Python stack overflow on pathological inputs before they even reach flattening.
-
----
-
-## 8. Security Findings
-
-| Finding | Severity | Status |
-|---|---|---|
-| gunicorn CVE-2024-1135 (HTTP Request Smuggling) | High | Fix available: 22.0.0 |
-| gunicorn CVE-2024-6827 | Medium | Fix available: 22.0.0 |
-| requests CVE-2024-35195 | Medium | Fix available: 2.33.0 |
-| requests CVE-2024-47081 | Medium | Fix available: 2.33.0 |
-| requests CVE-2026-25645 | Medium | Fix available: 2.33.0 |
-| Flask CVE-2026-27205 | Medium | Fix available: 3.1.3 |
-| pytest CVE-2025-71176 | Low (test-only) | Fix available: 9.0.3 |
-| SSRF via API fetch | Mitigated | DNS validation + `allow_redirects=False` in place |
-| XSS in table rendering | Mitigated | `escapeHtml()` used on all dynamic content |
-| CSRF | Mitigated | Flask-WTF CSRFProtect on all POST routes |
-| Information leakage in API errors | Mitigated | Generic messages returned; details logged server-side |
-| `SECRET_KEY` default | Risk | Dev default documented; `generateValue: true` in render.yaml |
-
----
-
-## 9. Prioritized Execution Plan
-
-### Phase 1 — Security & CI Foundations (Day 1, ~3 hours, zero behavior change)
-
-**Goal:** Eliminate all CVEs, add CI gate before production deploys.
-
-| Step | File(s) | Command |
-|---|---|---|
-| 1a. Bump vulnerable deps | `requirements.txt` | Edit versions |
-| 1b. Split dev deps | `requirements-dev.txt` (new) | `pip install -r requirements-dev.txt` |
-| 1c. Add `LICENSE` | `LICENSE` (new) | Copy MIT template |
-| 1d. Add GitHub Actions CI | `.github/workflows/ci.yml` (new) | — |
-| 1e. Verify tests still pass | — | `python -m pytest tests/ -v` |
-| 1f. Run `pip-audit` clean | — | `pip-audit -r requirements.txt` |
-
-**`requirements.txt` after Phase 1:**
-```
-Flask==3.1.3
-requests==2.33.0
-gunicorn==22.0.0
-Flask-WTF==1.2.1
-Flask-Limiter==3.5.0
-openpyxl==3.1.5
-```
-
-**`requirements-dev.txt` after Phase 1:**
-```
--r requirements.txt
-pytest==9.0.3
-coverage==7.6.1
-ruff==0.4.4
-pip-audit==2.7.3
-```
-
-**`.github/workflows/ci.yml`:**
-```yaml
-name: CI
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-      - run: pip install -r requirements-dev.txt
-      - run: ruff check .
-      - run: ruff format --check .
-      - run: python -m pytest tests/ -v --tb=short
-      - run: pip-audit -r requirements.txt
-```
-
-**Acceptance criteria:**
-- `pip-audit -r requirements.txt` reports zero vulnerabilities.
-- All 82 tests pass.
-- CI workflow runs on every push/PR and goes green.
-
----
-
-### Phase 2 — Linting, Formatting & Quick Fixes (Day 1–2, ~2 hours)
-
-**Goal:** Enforce consistent code style; fix small DX/correctness issues.
-
-| Step | File(s) | Notes |
-|---|---|---|
-| 2a. Add `pyproject.toml` | `pyproject.toml` (new) | ruff + pytest config |
-| 2b. Run `ruff check . --fix` | All `.py` files | Auto-fix lint issues |
-| 2c. Fix hardcoded "25" in badge | `routes.py`, `static/js/app.js` | Return `preview_limit` in `/process` response |
-| 2d. Add `.env.example` | `.env.example` (new) | Safe placeholder values |
-| 2e. Add `Makefile` | `Makefile` (new) | `make test`, `make lint`, `make coverage` |
-| 2f. Update README dev section | `README.md` | Add lint + coverage commands |
-
-**`pyproject.toml`:**
-```toml
-[tool.ruff]
-target-version = "py311"
-line-length = 100
-
-[tool.ruff.lint]
-select = ["E", "F", "W", "I", "UP"]
-ignore = ["E501"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-```
-
-**Acceptance criteria:**
-- `ruff check .` exits 0.
-- `ruff format --check .` exits 0.
-- Preview badge correctly reflects server-side `PREVIEW_ROW_LIMIT`.
-- All 82 tests still pass.
-
----
-
-### Phase 3 — Test Coverage Improvements (Day 2–3, ~3 hours)
-
-**Goal:** Cover the remaining 18 uncovered lines; add edge-case inputs.
-
-| Step | File(s) | New tests |
-|---|---|---|
-| 3a. Auth method coverage | `tests/test_routes.py` | API key, basic auth, bearer token, query param |
-| 3b. No-file upload branch | `tests/test_routes.py` | POST file with no `json_file` field |
-| 3c. JSONL ValueError in API fetch | `tests/test_routes.py` | Mock API returning malformed JSONL |
-| 3d. Null/boolean/Unicode inputs | `tests/test_helpers.py` | `null`, `true`, `false`, `\u0000`, emoji column names |
-| 3e. Empty-object rows | `tests/test_helpers.py` | `[{}, {}]` input |
-| 3f. Large column count | `tests/test_helpers.py` | Object with 500 keys |
-| 3g. Security: invalid IPv6 formats | `tests/test_security.py` | IPv4-mapped IPv6 addresses |
-
-**Target coverage after Phase 3:** ≥97% overall, ≥90% routes.py.
-
-**Acceptance criteria:**
-- All new and existing tests pass.
-- `coverage report` shows ≥90% for `routes.py`.
-- `coverage report` shows ≥97% overall.
-
----
-
-### Phase 4 — Complexity & Refactoring (Day 3–4, ~4 hours)
-
-**Goal:** Reduce `process_json` complexity; extract shared serialization helper.
-
-| Step | File(s) | Notes |
-|---|---|---|
-| 4a. Extract `serialize_cell_value()` | `routes.py` | Used by both `export_csv` and `export_xlsx` |
-| 4b. Extract `_load_input()` helper | `routes.py` | Returns `(json_data, error_response_or_None)` |
-| 4c. Extract `_apply_path()` helper | `routes.py` | Path selection logic extracted |
-| 4d. Add depth guard to `extract_table_data()` | `helpers.py` | Mirror `flatten_for_csv` pattern |
-| 4e. Move `openpyxl` import to module top | `routes.py` | Consistency; fails fast on missing dep |
-| 4f. Update tests for refactored functions | `tests/test_routes.py` | No behavior change, same assertions |
-
-**Acceptance criteria:**
-- All existing tests pass unchanged.
-- `process_json` function body ≤ 50 lines.
-- No behavior change visible to API consumers.
-
----
-
-### Phase 5 — Type Annotations & Static Analysis (Day 4–5, ~3 hours)
-
-**Goal:** Add type hints to all Python modules; run mypy clean.
-
-| Step | File(s) | Notes |
-|---|---|---|
-| 5a. Add `mypy` to dev deps | `requirements-dev.txt` | `mypy==1.10.0` |
-| 5b. Add mypy config | `pyproject.toml` | `[tool.mypy]` section |
-| 5c. Annotate `helpers.py` | `helpers.py` | All function signatures |
-| 5d. Annotate `security.py` | `security.py` | Return `tuple[bool, str | None]` |
-| 5e. Annotate `config.py` | `config.py` | Class attribute types |
-| 5f. Annotate `routes.py` | `routes.py` | After refactor in Phase 4 |
-| 5g. Add mypy to CI | `.github/workflows/ci.yml` | `- run: mypy .` |
-
-**Acceptance criteria:**
-- `mypy . --ignore-missing-imports` exits 0.
-- No runtime behavior change.
-
----
-
-### Phase 6 — Documentation & DX Polish (Day 5, ~2 hours)
-
-**Goal:** Close remaining documentation gaps; improve contributor experience.
-
-| Step | File(s) | Notes |
-|---|---|---|
-| 6a. Add `CONTRIBUTING.md` | `CONTRIBUTING.md` (new) | Setup, lint, test, PR checklist |
-| 6b. Add `CHANGELOG.md` | `CHANGELOG.md` (new) | Starting from v1.1.0 |
-| 6c. Update README | `README.md` | Add lint, type-check, coverage commands; fix missing LICENSE note; link CONTRIBUTING |
-| 6d. Add JSON edge-case examples | `README.md` | Null, boolean, Unicode, mixed-type arrays |
-| 6e. Fix `alert()` in About | `static/js/app.js` | Replace with accessible modal or `<dialog>` |
-| 6f. Keyboard-accessible export dropdown | `static/js/app.js`, `templates/index.html` | Add `aria-expanded`, focus trap, Escape key close |
-
-**Acceptance criteria:**
-- A new contributor can set up the project, run lint, run tests, and view coverage using only `README.md` + `CONTRIBUTING.md`.
-- `CHANGELOG.md` exists.
-- Export dropdown is reachable by keyboard.
-- No `alert()` calls in production code.
-
----
-
-## 10. Implementation Checklist
-
-### Phase 1 — Security & CI
-- [ ] Upgrade `Flask` to `3.1.3` in `requirements.txt`
-- [ ] Upgrade `requests` to `2.33.0` in `requirements.txt`
-- [ ] Upgrade `gunicorn` to `22.0.0` in `requirements.txt`
-- [ ] Upgrade `openpyxl` to `3.1.5` in `requirements.txt`
-- [ ] Move `pytest` out of `requirements.txt`, create `requirements-dev.txt`
-- [ ] Add `ruff`, `coverage`, `pip-audit` to `requirements-dev.txt`
-- [ ] Add `pytest==9.0.3` to `requirements-dev.txt`
-- [ ] Create `LICENSE` file (MIT)
-- [ ] Create `.github/workflows/ci.yml`
-- [ ] Verify `pip-audit -r requirements.txt` → 0 vulnerabilities
-- [ ] Verify all 82 tests pass with new dependency versions
-
-### Phase 2 — Linting & Quick Fixes
-- [ ] Create `pyproject.toml` with ruff + pytest config
-- [ ] Run `ruff check . --fix` and commit
-- [ ] Add `preview_limit` field to `/process` JSON response
-- [ ] Update `app.js` to use `data.preview_limit` for badge text
-- [ ] Create `.env.example`
-- [ ] Create `Makefile`
-- [ ] Update README development section
-- [ ] `ruff check .` exits 0
-- [ ] `ruff format --check .` exits 0
-
-### Phase 3 — Test Coverage
-- [ ] Test all four auth methods (api_key, basic, bearer, query_param)
-- [ ] Test missing `json_file` field in file upload
-- [ ] Test JSONL parse error from API fetch
-- [ ] Test null/boolean/Unicode column names in helpers
-- [ ] Test empty-object rows `[{}, {}]`
-- [ ] Coverage report shows ≥90% routes.py
-- [ ] Coverage report shows ≥97% overall
-
-### Phase 4 — Complexity Reduction
-- [ ] Extract `serialize_cell_value(v)` helper in `routes.py`
-- [ ] Extract `_load_input(request, data_format)` from `process_json`
-- [ ] Extract `_apply_path(json_data, json_path)` from `process_json`
-- [ ] Add `_depth` guard to `extract_table_data()`
-- [ ] Move `openpyxl` import to module top in `routes.py`
-- [ ] `process_json` body ≤ 50 lines
-- [ ] All existing tests pass
-
-### Phase 5 — Type Annotations
-- [ ] Annotate all functions in `helpers.py`
-- [ ] Annotate all functions in `security.py`
-- [ ] Annotate `Config` class in `config.py`
-- [ ] Annotate route functions in `routes.py`
-- [ ] `mypy . --ignore-missing-imports` exits 0
-- [ ] Add mypy step to CI workflow
-
-### Phase 6 — Documentation & DX
-- [ ] Create `CONTRIBUTING.md`
-- [ ] Create `CHANGELOG.md`
-- [ ] Update README: lint/type-check/coverage commands, remove "Feature Requests" references to missing issue tracker
-- [ ] Add JSON edge-case examples to README
-- [ ] Replace `alert()` with accessible modal in `app.js`
-- [ ] Make export dropdown keyboard-accessible
-- [ ] A first-time contributor can complete setup in < 5 minutes using only docs
-
----
-
-## 11. Final Verification Checklist
-
-Run all of these after completing all phases:
-
-```bash
-# 1. Install production deps and audit
-pip install -r requirements.txt
-pip-audit -r requirements.txt
-# Expected: 0 vulnerabilities
-
-# 2. Install dev deps
-pip install -r requirements-dev.txt
-
-# 3. Lint
-ruff check .
-# Expected: 0 issues
-
-# 4. Format check
-ruff format --check .
-# Expected: no reformatting needed
-
-# 5. Type check
-mypy . --ignore-missing-imports
-# Expected: 0 errors
-
-# 6. Run full test suite
-python -m pytest tests/ -v
-# Expected: all tests pass, 0 failures, 0 errors
-
-# 7. Coverage
-coverage run -m pytest tests/ && coverage report -m
-# Expected: ≥97% overall, ≥90% routes.py
-
-# 8. CI workflow validation (local with act, or inspect YAML)
-# All steps in .github/workflows/ci.yml pass
-
-# 9. Dev server smoke test
-FLASK_DEBUG=1 python app.py
-# Expected: starts on port 5000, /health returns {"status":"ok","version":"1.1.0"}
-# curl http://localhost:5000/health
-
-# 10. Export smoke test
-# POST /process with sample JSON → preview renders
-# Export CSV, TSV, Excel → files download correctly
-
-# 11. SSRF smoke test
-# POST /process with api_url=http://169.254.169.254/ → 400, "private"
-
-# 12. CSRF smoke test
-# POST /process without csrf_token → 400 (CSRF protection active outside test mode)
-
-# 13. Security headers check
-# curl -I http://localhost:5000/ | grep -E "(CSP|X-Frame|X-Content|Referrer)"
-```
-
----
-
-## 12. Remaining Risks & Tradeoffs
-
-| Risk | Likelihood | Mitigation |
-|---|---|---|
-| DNS rebinding (SSRF residual) | Low | Documented in `routes.py` comment; mitigated by `allow_redirects=False` |
-| Memory exhaustion on deeply nested JSON (recursive `extract_table_data`) | Low | Fix in Phase 4; `max_depth` guard already on `flatten_for_csv` |
-| `SECRET_KEY` misconfiguration in production | Medium | `render.yaml` uses `generateValue: true`; README warns; add startup assertion |
-| Browser tab freeze on large nested cell values | Low | Phase 6: cap nested table rendering at N cells |
-| openpyxl `DeprecationWarning` (internal) | Info | Will resolve with openpyxl upstream; pin to 3.1.5+ |
-| Transitive dep version drift | Medium | Add `pip-compile` / lock file in post-85 iteration |
-
----
-
-## 13. Projected Score After All Phases
-
-| Category | Current | Projected |
-|---|---|---|
-| Maintainability | 7/10 | 9/10 |
-| Test coverage & quality | 8/10 | 9/10 |
-| Complexity | 7/10 | 9/10 |
-| Duplication | 8/10 | 9/10 |
-| Architecture consistency | 8/10 | 9/10 |
-| Dependency / security risk | 3/10 | 9/10 |
-| Documentation | 7/10 | 9/10 |
-| CI/CD reliability | 0/10 | 9/10 |
-| Input validation & error handling | 9/10 | 10/10 |
-| Usability & developer experience | 7/10 | 9/10 |
-| **Overall weighted** | **~68/100** | **~91/100** |
-
-The two categories with the largest score gain are **CI/CD** (0→9) and **Dependency/Security** (3→9), which together account for +30% of the overall score improvement. Both are achievable in Phase 1 with low effort and zero behavior change.
-
----
-
-*Report generated: 2026-05-02. Review the [implementation checklist](#10-implementation-checklist) to track progress.*
diff --git a/docs/export-budget-v1.2.md b/docs/export-budget-v1.2.md
deleted file mode 100644
index 3fbfec8..0000000
--- a/docs/export-budget-v1.2.md
+++ /dev/null
@@ -1,113 +0,0 @@
-# XLSX export budget — how `MAX_EXPORT_CELLS` was measured
-
-**Date:** 2026-08-21
-**Applies to:** roadmap task 2.3 / D6, performance finding P3.
-**Result:** `DEFAULT_MAX_EXPORT_CELLS = 250_000` cells (`config.py`).
-
-D6 requires the guard's default to come from the Performance Review §4
-measurement rather than being chosen by feel. This file records the numbers it
-was derived from, so it can be re-derived when the measurement is re-run.
-
-## Method
-
-Performance Review §4's protocol, with one documented deviation.
-
-Followed as written:
-
-| Parameter | This run |
-|---|---|
-| Units | `ru_maxrss` read on Linux (KiB), multiplied by 1024, reported in MiB |
-| Peak | `resource.getrusage(RUSAGE_SELF).ru_maxrss`, read after the response was fully delivered |
-| No warm-up in a measured process | Each measured process serves **exactly one** request, then exits |
-| Two runs, not two samples | `baseline` = a freshly booted process that served **zero** requests; `measured` = a freshly booted process that served exactly one. `delta = measured − baseline` |
-| Concurrency | 1 |
-| Absolute and delta | Both recorded |
-| Blocked pairs | None occurred; none were discarded |
-
-**Deviation:** requests were issued through the Flask test client inside a fresh
-Python process rather than through a fresh gunicorn worker, and the sizing sweep
-used one run-pair per shape rather than the median of three. The property the
-protocol exists to protect — that `ru_maxrss` is monotonic per process and so
-cannot be reset mid-process — is preserved: every measured number comes from a
-process that served exactly one request. Numbers produced this way are
-comparable to each other but should not be quoted against the §4 budget as if
-they had come from the full gunicorn/median-of-three protocol.
-
-`MAX_CONTENT_LENGTH` was raised for the measurement only, so request-body size
-would not mask the workbook cost.
-
-## Data
-
-| rows × cols | cells | delta (MiB) | absolute (MiB) |
-|---|---|---|---|
-| 15,000 × 10 | 150,000 | 73.6 | 114.3 |
-| 83,333 × 3 | 249,999 | **138.9** | 179.6 |
-| 50,000 × 3 | 150,000 | **84.3** | 125.0 |
-| 20,000 × 10 | 200,000 | 98.6 | 139.2 |
-| 2,000 × 150 | 300,000 | 137.3 | 178.0 |
-| 91,666 × 3 | 274,998 | **152.2** | 193.0 |
-| 100,000 × 3 | 300,000 | **161.7** | 202.4 |
-| 40,000 × 10 | 400,000 | 195.6 | 236.3 |
-
-At equal cell counts the **narrow, tall** shape is consistently the most
-expensive (84.3 vs 73.6 MiB at 150,000 cells; 161.7 vs 137.3 at 300,000) —
-openpyxl carries per-row overhead on top of per-cell. Three columns is therefore
-the worst aspect ratio tested and the one the budget is sized against.
-
-This is also why the budget is expressed in **cells** rather than rows: 50,000
-rows costs 84.3 MiB at 3 columns and 40,000 rows costs 195.6 MiB at 10, so a row
-count says almost nothing about the footprint on its own.
-
-## Derivation
-
-Fitting the two bracketing points of the 3-column series:
-
-```text
-(150,000 cells, 84.3 MiB) and (274,998 cells, 152.2 MiB)
-slope     = 0.000543 MiB/cell
-intercept = 2.8 MiB
-150 MiB crossing = (150 − 2.8) / 0.000543 ≈ 270,900 cells
-```
-
-The 274,998-cell run measured **152.2 MiB — over the 150 MiB target**, so the
-crossing is real and not an artifact of extrapolation. The budget is set at
-**250,000 cells**, roughly 8% below the crossing, which is the margin
-run-to-run variance on these measurements needs.
-
-That value was then measured directly rather than left as an extrapolation:
-83,333 × 3 = 249,999 cells came back at **138.9 MiB delta / 179.6 MiB absolute**
-(the fit predicted 138.6). It passes both halves of the §4 verdict — under the
-150 MiB delta target, and well under the 256 MiB absolute ceiling for a 512 MiB
-container.
-
-## What the budget does and does not cover
-
-- It is **XLSX-only**. CSV and TSV are generator-streamed and stay uncapped, so
-  every dataset `/process` accepts remains exportable by some route. That, not
-  an unbounded XLSX path, is what keeps the export contract as wide as the input
-  contract.
-- It is **enabled by default**. An unlimited default would leave P3 (High)
-  unmitigated. `MAX_EXPORT_CELLS=0` disables it for operators who knowingly opt
-  out.
-- It is **advertised, never silent**. `/process` returns `total_cells` and
-  `max_export_cells` so the client greys the Excel entry out before the user
-  clicks; `/export-xlsx` independently returns 400 for direct API callers. There
-  is no truncation — a partial spreadsheet is worse than a refusal.
-- The 10 MiB request cap makes memory finite but not usefully bounded: the
-  JSON → Python → openpyxl → zip expansion multiplier is large and
-  data-dependent. The measured cell budget is the bound; the request cap is not
-  a substitute for it.
-
-## Reproducing
-
-The harness is not committed (it is a throwaway measurement script, and the
-roadmap keeps perf tests out of CI). It does two things:
-
-1. `baseline`: boot `create_app()`, serve nothing, print `ru_maxrss`.
-2. `measured`: boot `create_app()`, POST one synthetic `csv_data` body of
-   `rows × cols` cells to `/export-xlsx` with `MAX_EXPORT_CELLS=0`, assert 200,
-   then print `ru_maxrss`.
-
-Run each in its own process and subtract. Re-derive the fit above from at least
-two points on the narrowest aspect ratio you care about, and re-run the
-confirming point at the value you intend to ship.
diff --git a/docs/performance-review-v1.2.md b/docs/performance-review-v1.2.md
deleted file mode 100644
index 9ce26d6..0000000
--- a/docs/performance-review-v1.2.md
+++ /dev/null
@@ -1,262 +0,0 @@
-# Performance Review — JSON Table Converter (v1.2 planning)
-
-**Date:** 2026-08-20
-**Scope:** `routes.py`, `helpers.py`, `security.py`, `static/js/app.js`, `config.py`, `render.yaml`
-**Method:** Static analysis of the hot paths (parse → flatten → serialize → render → export). No benchmarks could be run in this sandbox (no pip); sizing figures are conservative estimates based on the code paths. Design constraints respected: **no server-side persistence of payloads** (the full-dataset-in-response design is deliberate — see §5) and **no frontend framework/build step**.
-
----
-
-## 1. Executive Summary
-
-The app's heavy operations are all in `/process` (parse + flatten + full-dataset response) and the export routes. With the default 10 MB input cap, a single request can hold **input JSON + flattened rows + response JSON in memory at once**, and the client downloads the *entire* dataset even though it only displays 25 preview rows. The single highest-leverage fix is **gzip compression of `/process` responses** (typical JSON compresses 5–10×). Second is **diskless, memory-bounded exports** (capped workbook + generator responses — no OS temp files). Frontend, the **eager JSON tree picker** and **unbounded nested-cell rendering** are the freeze risks.
-
-| Severity | Count | Items |
-|---|---|---|
-| High | 2 | P1 Uncompressed multi-MB JSON responses, P3 XLSX export memory (openpyxl non-streaming + full buffering) |
-| Medium | 6 | P2 Full dataset shipped per request, P4 Eager tree-picker DOM build, P5 Unbounded nested-cell render/stringify, P7 Blocking DNS lookup in worker, P9 Gunicorn timeout vs `API_FETCH_TIMEOUT` misalignment, P12 Multi-copy memory in `process_json` |
-| Low | 4 | P6 No static-asset cache headers, P8 Double column scan + wasteful flatten intermediates, P10 Dead code `find_candidate_arrays`, P11 Hardcoded "25" preview badge |
-| Info | 1 | P13 Client-side CSV/TSV string building |
-
-**Quick wins:** P1 (gzip), P6 (cache headers), P8 (one-pass columns), P10 (dead code), P11 (preview_limit in payload).
-
----
-
-## 2. Findings
-
-### P1 — Large `/process` JSON responses are uncompressed — **High**
-
-**Location:** `routes.py:188-195` (response), no gzip middleware anywhere.
-
-**Description:** `/process` returns `preview` + `csv_data` (the **full** flattened dataset) + `csv_columns`. For a 10 MB JSON input the response body is commonly 5–20 MB of repetitive JSON. No compression layer exists (Flask serves it raw; gunicorn's default setup doesn't gzip; Nginx config in README has no `gzip`). Text/JSON compresses 5–10×, so gzip is the largest single transfer-time and bandwidth win available. It does **not** reduce the client's uncompressed `csv_data` representation or its JSON parse cost — the browser still receives, decompresses, parses, and stores the full dataset; those are P2 (payload size) and P5 (rendering) concerns.
-
-**Remediation:** Add a small gzip middleware (Flask `after_request`) that compresses only when the response is eligible: `Accept-Encoding` includes gzip, the body is text/JSON over ~1 KB, and the response is compressible — skip bodyless responses, `HEAD`/`204`/`304`, bodies already carrying a `Content-Encoding`, and streamed responses (`response.is_streamed`, which covers the streaming export routes). Set `Content-Encoding: gzip` and `Vary: Accept-Encoding`, and remove or recompute `Content-Length` so it matches the compressed payload. Avoid adding a dependency unless preferred — a ~20-line middleware in `app.py`/`security.py` fits the project's minimal-deps stance. If a dependency is acceptable, `Flask-Compress` is the standard choice (pin exactly).
-
-**Effort:** 1h. **Verification:** `curl -H 'Accept-Encoding: gzip' -s -o /dev/null -w '%{size_download} %{time_total}'` on a large `/process` call before/after; compare sizes.
-
----
-
-### P2 — Full dataset shipped to the client on every `/process` — **Medium** (design-constrained)
-
-**Location:** `routes.py:185-194`.
-
-**Description:** The server flattens **all** rows (`csv_data = [flatten_for_csv(row, ...) for row in table_data]`) and serializes them all to the client, although only `PREVIEW_ROW_LIMIT` (25) rows are rendered. Cost: server CPU for full flattening, ~3× peak memory (input + rows + response), full payload transfer, client memory, client parse time. The design is deliberate — CSV/TSV export is client-side from `csv_data`, and the no-persistence rule forbids holding the dataset server-side between requests (`MEMORY.md` 2026-05-12). **Do not** fix by caching payloads server-side.
-
-**Remediation options (in order of fit):**
-1. **Compress the response (P1)** — reduces transfer size/time without changing the architecture (client parse and memory cost are unchanged; see P2/P5).
-2. **Stream-aware preview truncation** — server-side cap nested values/long strings inside `preview` rows only (keep full fidelity in `csv_data`). Cheap, prevents the worst client-render cases (see P5).
-3. **Client-side lazy rendering** — the data is already in the browser; implement "load more" pagination over `csv_data` so the DOM only ever holds a window of rows (also a feature; roadmap Phase 4).
-
-**Effort:** P1: 1h; option 2: 30m; option 3: 2-3h (feature).
-
----
-
-### P3 — XLSX export is fully buffered in memory — **High**
-
-**Location:** `routes.py:245-289`.
-
-**Description:** `Workbook()` (normal mode) holds all rows in memory, and `wb.save(output)` + `output.getvalue()` create a second full copy (plus the JSON request body already holds `csv_data`). With a ~10 MB `csv_data` payload the request can transiently consume several hundred MB — enough to OOM a free-tier dyno and a 413-adjacent DoS amplifier (60/min limit only partially mitigates). CSV export (`routes.py:217-238`) has the same pattern with `io.StringIO` (smaller but still full-buffer).
-
-**Remediation:**
-- **Diskless by default.** openpyxl's `write_only=True` mode writes worksheet parts to OS temporary files, which conflicts with the absolute "no disk writes of payloads" rule. `tempfile.SpooledTemporaryFile` is not the diskless escape hatch it looks like, but not for the usual reason: with its **default `max_size=0` it never rolls over on write at all** (`_check()` tests `if max_size and tell() > max_size`, so a zero threshold is falsy) — it is then a `BytesIO` with extra indirection and **zero** memory benefit, which is the actual reason it fails to solve P3. Set a non-zero `max_size` and it *does* write payload bytes to an OS temp file once that threshold is crossed; and any call to `fileno()` (or `rollover()`) forces the disk file regardless of threshold. So it is either pointless or disk-backed — never both diskless and memory-light. The diskless path is a normal-mode `Workbook` plus the `MAX_EXPORT_CELLS` budget below, which bounds peak memory without touching disk. The memory-light temp-file route is only acceptable under an explicit documented exception (roadmap D6). Note that even `write_only=True` does not eliminate the final `save()` zip assembly.
-- **The XLSX guard is enabled by default, budgeted in cells, and never a silent rejection.** An unlimited default would leave P3 — a High finding — unmitigated, which is the whole point of this item. What was wrong in the first pass was not *having* a guard but expressing it as a fixed row count that could reject data `/process` had already accepted, with no warning and no route forward. Both properties are achievable at once:
-  - **Budget in cells, not rows, and keep it on.** openpyxl memory tracks `rows × columns`: a 10 MiB body with 3 columns and one with 500 columns have wildly different footprints at the same row count. The guard is `MAX_EXPORT_CELLS`, **enabled by default**, with the default derived from the §4 measurement as the largest cell count that holds peak RSS inside the 150 MiB export target on the worst aspect ratio tested. Re-derive it whenever that measurement is re-run; do not pick a round number by feel. `0` disables it, for operators who knowingly opt out.
-  - **A bounded input is not a bounded footprint.** `/export-xlsx` bodies are already capped by `MAX_CONTENT_LENGTH` (10 MiB), so peak memory is *finite* — but the JSON → Python → openpyxl → zip expansion multiplier is large and data-dependent, so "finite" is not a useful operating bound. The measured cell budget is the bound; the request cap is not a substitute for it. The guard is **XLSX-only**: CSV/TSV are generator-streamed and stay uncapped, so every dataset `/process` accepts remains exportable by some route. That, rather than an unlimited XLSX path, is what keeps the export contract at least as wide as the input contract.
-  - **Advertised, never silent.** `/process` already returns `total_rows` (`routes.py:192`) — reuse it, do not add a second row-count field. The new keys are `total_cells` (`total_rows × len(csv_columns)`) and `max_export_cells`, echoing the effective limit. Client rule: disable the Excel entry iff `max_export_cells > 0 && total_cells > max_export_cells`, labelling it "too large for Excel — use CSV/TSV" *before* the user clicks. `/export-xlsx` independently returns `400 {"error": "Dataset is N cells, above the Excel export limit of M; export CSV or TSV instead."}` (defence in depth for direct API callers). No silent truncation: a partial spreadsheet is worse than a refusal.
-- Deliver via `send_file`/`Response(iter)`; do **not** `output.getvalue()` the whole buffer into memory.
-- For CSV: use a generator-based `Response` that yields rows (`csv` writer needs a text wrapper — yield `''.join`-chunked or use `io.StringIO` flush per N rows). CSV is natively streamable with no temp files. Keep `extrasaction='ignore'` and the F1 sanitization.
-
-**Effort:** 2h. **Verification:** export 100k rows and measure RSS **during generation and during response delivery** — do not infer bounded memory from a missing `Content-Length` or chunked transfer, since those only indicate streaming, not peak usage.
-
----
-
-### P4 — JSON tree picker builds the entire tree eagerly — **Medium**
-
-**Location:** `static/js/app.js:161-247` (`showTreePicker`/`buildTreeNode`).
-
-**Description:** `showTreePicker(raw_json)` recursively builds DOM nodes for **every** key of every object (only array *lengths* are capped at 50 children). A 10 MB payload with a wide/deep structure → tens of thousands of DOM nodes synchronously → multi-second freeze and large memory spike. Objects are fully expanded into the tree regardless of whether the user opens them.
-
-**Remediation:** Lazy build: render the root and, on first toggle of a node, build that node's children (`data-loaded` flag / `MutationObserver`-free approach). Cap per-level children (e.g. 200) with "…and N more" placeholders (already done for arrays at 50 — extend the pattern to objects and to total tree nodes).
-
-**Effort:** 2h. **Verification:** open a 50 MB-ish structure (bounded by 10 MB upload) in the picker; DevTools Performance shows no long task; toggling builds incrementally.
-
----
-
-### P5 — Unbounded nested-cell rendering / stringification — **Medium**
-
-**Location:** `static/js/app.js:364-387` (`formatValue`), `390-405` (`renderNestedObject`), `408-438` (`renderNestedTable`), plus server `routes.py:182` (`preview_data`).
-
-**Description:**
-- `renderNestedObject` renders **all** keys of a nested object — an object with 50k keys → 50k `<tr>` in one cell → freeze.
-- `formatValue` for arrays of primitives does `JSON.stringify(value)` over the **whole** array (a 100k-item array → huge string in one `td`).
-- A single very long string cell (e.g. 5 MB base64) renders in full.
-- Server side, `preview` rows carry full-fidelity nested structures, so all of the above are fed directly by the API.
-
-**Remediation (server + client):**
-- Server: truncate in `preview` only, **without mutating shared objects** — build a separate preview projection (copy) so `table_data`/`csv_data` keep full fidelity; add a test asserting exports still contain untruncated values. Long strings → ~256 chars, nested arrays → ~20 items, nested objects → ~20 keys, with `"… (truncated)"` markers.
-- Client: cap `renderNestedObject` keys (e.g. 20 + "and N more"); cap `JSON.stringify` length for primitive arrays (render first N + count); add `max-width`/ellipsis already present via CSS but ensure no full-string `innerHTML` blow-ups.
-
-**Effort:** 1-2h. **Verification:** cell containing a 10k-key object renders < 1 s and < N MB heap.
-
----
-
-### P6 — No cache headers on static assets — **Low**
-
-**Location:** `app.py` (no `SEND_FILE_MAX_AGE_DEFAULT`), `templates/index.html:11,237`.
-
-**Description:** `style.css` and `app.js` are served via Flask's static handler with `Last-Modified`/304 support but **no `Cache-Control`**, so browsers revalidate every navigation. On the Render free tier (cold starts) this adds a round-trip per page load and extra requests during the cold window.
-
-**Remediation:** In `config.py`: `SEND_FILE_MAX_AGE_DEFAULT = int(os.environ.get('STATIC_MAX_AGE', 86400))`; optionally add cache-busting query (`?v={{ config.APP_VERSION }}`) on the two asset URLs in `index.html`. Don't set a huge max-age without versioning, or updates will be stale.
-
-**Effort:** 20m.
-
----
-
-### P7 — Blocking DNS lookup inside the request path — **Medium**
-
-**Location:** `security.py:24` (`socket.getaddrinfo`), called synchronously in `routes.py:82`.
-
-**Description:** DNS resolution runs on the gunicorn worker thread with **no timeout** (see Security Review F6). A slow/malicious nameserver ties up the worker for seconds-to-minutes; with few workers (free tier defaults to 1-2), one request can stall the whole app. Also adds per-request latency to every API fetch (usually 5-50ms, but unbounded worst case).
-
-**Remediation:** Use a **shared, module-level** `ThreadPoolExecutor` with a fixed `max_workers` and an in-flight semaphore; wait via `future.result(timeout=API_DNS_TIMEOUT)` (default ~3s) and return the existing invalid-URL error on timeout. Do **not** create a per-request executor — `result(timeout=...)` bounds only the caller's wait and cannot cancel a running `getaddrinfo` (per-request executors leak blocked threads; a shared unbounded pool can saturate). A *hard* execution bound needs process isolation or a cancellable resolver; document the timeout as a wait bound. Do **not** rely on memoizing validated hostnames as a rebinding control — a cached approval can differ from the address the client actually connects to; hostname caching (if ever added) is a latency optimization only, never a security control.
-
-**Effort:** 1h. **Verification:** mock `getaddrinfo` sleeping 10s → `/process` returns in ~3s; no worker stall.
-
----
-
-### P8 — Double column scan + costly flatten intermediates — **Low**
-
-**Location:** `routes.py:180-186`, `helpers.py:17-31`.
-
-**Description:**
-- `get_all_columns(table_data)` and `get_all_columns(csv_data)` each do a full pass; flattening does a third.
-- `flatten_for_csv` builds a `list` of tuples and then a `dict` for every row (`items = []` … `dict(items)`) — extra allocation per row, per level.
-- `json.dumps` is called for every list-valued cell even when the row will only appear in the preview.
-
-**Remediation:** One pass that both flattens and accumulates column names: collect names into a set during flattening and **sort once at the end** — this preserves the current `get_all_columns` sorted-output contract (do not rely on set iteration order, which is insertion-order-dependent); build the result dict directly instead of list-of-tuples. Micro-optimizations — measurable only on very large inputs, bundle with P2 work, and verify that `csv_columns`/rendered column order is byte-identical to today.
-
-**Effort:** 1h. **Verification:** same outputs; `get_all_columns` result identical.
-
----
-
-### P9 — Gunicorn worker timeout vs `API_FETCH_TIMEOUT` — **Medium** (reliability/performance)
-
-**Location:** `render.yaml:9`, README gunicorn invocations, `config.py:16`.
-
-**Description:** `API_FETCH_TIMEOUT` defaults to 30s and gunicorn's default `--timeout` is also 30s. An API fetch that takes ~30s races the worker kill: gunicorn SIGKILLs the worker mid-response → client sees 502, worker respawn cost, request fails with a confusing error. None of the documented gunicorn invocations set `--timeout` or `--workers`.
-
-**Remediation:** Set `--timeout 60` (≥ API_FETCH_TIMEOUT × 2) in `render.yaml` and README/Docker/systemd examples; make the relationship explicit in config docs. Optionally lower `API_FETCH_TIMEOUT` to 15s for snappier failures. Keep **one worker and one instance** as the documented default: topology is coupled to rate-limit correctness (`memory://` counters are process-local, so the limit is multiplied by `workers × replicas`), so `--workers 2`, the README's `--workers 4` examples, and any `numInstances > 1` require a shared `RATELIMIT_STORAGE_URI` first (roadmap 2.10).
-
-**Effort:** 15m. **Verification:** a 35s mock API fetch no longer returns 502.
-
----
-
-### P10 — Dead code: `find_candidate_arrays` — **Low**
-
-**Location:** `helpers.py:82-111`; imported nowhere in `routes.py` (routes return `raw_json` for the tree picker instead).
-
-**Description:** The function and its 4 tests (`tests/test_helpers.py:110-134`) exist solely for the **old** candidates handshake replaced by the JSON tree picker (commit `e537042`). It is recursive without a depth guard (security finding F8) and confuses contributors reading the code (and the docs — see F17).
-
-**Remediation:** Delete the function and its 4 tests (decided in roadmap D2, executed in Phase 0.8) and update the stale `MEMORY.md`/`CLAUDE.md`/`AGENTS.md` descriptions. Repurposing it to pre-populate the tree picker is explicitly not chosen.
-
-**Effort:** 15m.
-
----
-
-### P11 — Hardcoded preview badge ("25") vs server config — **Low** (correctness/UX)
-
-**Location:** `static/js/app.js:321-326`, `routes.py:181` (`PREVIEW_ROW_LIMIT`).
-
-**Description:** `if (totalRows > 25) … 'Showing first 25'` hardcodes 25; an operator changing `PREVIEW_ROW_LIMIT` gets a wrong badge (and the earlier code-health review flagged the same). Sort also operates only on the 25 preview rows while exports contain all rows — order discrepancy users can't see.
-
-**Remediation:** Return `preview_limit` in the `/process` payload and use it in the badge. Document "sort applies to the visible preview only" or upgrade to full-dataset client sort when rows are loaded (Phase 4 feature).
-
-**Effort:** 20m + 2h (feature).
-
----
-
-### P12 — Multi-copy memory inside `process_json` — **Medium**
-
-**Location:** `routes.py:130-143` (API path), `routes.py:180-195`.
-
-**Description:** Peak memory during `/process` (API path): streamed `bytearray` → `bytes(content)` copy → decoded `str` → parsed JSON objects → flattened rows → `jsonify` string — roughly 4-6× the payload size, plus JSON encoder overhead. Upload/paste paths skip the first two copies. For 10 MB inputs this is ~40-60 MB transient; with default free-tier memory (~512 MB) and a few concurrent requests this is the realistic OOM risk.
-
-**Remediation:** Drop the intermediate `bytes(content)` copy (decode the `bytearray` directly via `content.decode('utf-8')`) — this removes one copy only. Parsing, flattening, and `jsonify` still materialize the full dataset, and gzip applied after `jsonify` does **not** reduce that peak. Do not treat post-parse size measurement as a peak-memory guard; either add a pre-parse/streaming input limit (an effective cap on what can be submitted) or document the full-pipeline multiplier and set the §4 budget accordingly.
-
-**Effort:** 30m + testing.
-
----
-
-### P13 — Client-side CSV/TSV string building — **Info**
-
-**Location:** `static/js/app.js:482-513`.
-
-**Description:** `downloadDelimited` concatenates the entire file into one string, then a Blob. For ~10 MB datasets this is a ~10-30 MB string + Blob copy → brief main-thread block and double memory. Acceptable at current scale.
-
-**Remediation:** Optional: write to the Blob in chunks (`Blob([part1, part2, …])`) — trivial change, avoids one giant string. Include F1 sanitization in the same pass.
-
----
-
-## 3. Finding-to-Remediation Matrix
-
-| ID | Finding | Severity | Remediation | Effort |
-|---|---|---|---|---|
-| P1 | No response compression | High | gzip middleware (guards + Content-Length fix) | 1h |
-| P3 | XLSX/CSV fully buffered | High | Diskless capped export (or D6 temp-file exception); generator | 2h |
-| P2 | Full dataset shipped per request | Medium | P1 + preview truncation + lazy render (design-constrained) | 1h + feature |
-| P4 | Eager tree-picker DOM | Medium | Lazy children build + caps | 2h |
-| P5 | Unbounded nested-cell render | Medium | Non-mutating preview projection + client caps | 1-2h |
-| P7 | Blocking DNS in worker | Medium | Shared bounded resolver + in-flight limit (shared with F6) | 1h |
-| P9 | gunicorn timeout < API timeout | Medium | `--timeout 60` everywhere | 15m |
-| P12 | Multi-copy memory in `/process` | Medium | Drop `bytes()` copy; document full-pipeline peak | 30m |
-| P6 | No static cache headers | Low | `SEND_FILE_MAX_AGE_DEFAULT` + versioned URLs | 20m |
-| P8 | Double column scan / tuple dicts | Low | Single-pass flatten + sorted columns (order-preserving) | 1h |
-| P10 | Dead code `find_candidate_arrays` | Low | Delete + doc sync | 15m |
-| P11 | Hardcoded "25" badge | Low | `preview_limit` in payload | 20m |
-| P13 | Client CSV giant string | Info | Chunked Blob | 15m |
-
----
-
-## 4. Recommended Perf Budget (acceptance targets for v1.2)
-
-Measured on a reference payload (10 MB, ~200k rows of mixed nesting), single free-tier worker:
-
-| Metric | Current (est.) | Target |
-|---|---|---|
-| `/process` transfer size | ~10-20 MB | ≤ 2-4 MB (gzip) |
-| `/process` p95 latency (paste/upload only) | seconds (unbounded) | ≤ 3s |
-| Peak RSS **delta**, `/process` (10 MB input) | ~40-60 MiB | **≤ 50 MiB** delta (pass/fail), absolute high-water < 256 MiB |
-| Peak RSS **delta**, `/export-xlsx` 100k rows | hundreds of MiB (OOM risk) | **≤ 150 MiB** delta (pass/fail), absolute high-water < 256 MiB, streams |
-| Tree-picker open, 10 MB payload | multi-second freeze | ≤ 500 ms initial; lazy children |
-| Cell with 10k-key object | freeze | renders ≤ 20 keys + "more" |
-| Static assets | revalidated every load | cached ≥ 1 day |
-
-The latency target explicitly **excludes API-fetch requests** — those are bounded separately by `API_FETCH_TIMEOUT` (default 30s) plus DNS time (P7/F6) and would otherwise make a single aggregate p95 meaningless. The peak-RSS target reflects the full parse → flatten → `jsonify` pipeline (P12); it is not a claim that gzip or dropping one copy makes the process fit under 30 MB.
-
-**RSS measurement method (identical for `/process` and for the export measurement — both rows are pass/fail against these exact rules). Note `ru_maxrss` is a per-process high-water mark that cannot be reset, which drives the fresh-worker protocol below:**
-
-| Parameter | Definition |
-|---|---|
-| Units | **`ru_maxrss` is not portable.** On Linux it is **KiB**; on macOS/Darwin the same field is **bytes**. Read it, multiply by 1024 on Linux, and report everything in **MiB** (1 MiB = 1048576 bytes). Every memory threshold in this budget is written in **MiB**, not decimal MB. A harness that skips the platform conversion silently reports numbers 1024× off. |
-| Environment parity | Both runs of a pair must execute on the **same OS and kernel, the same container image, the same Python build, and the same cgroup/container resource limits**, on an otherwise idle host. A baseline from one image and a measurement from another is not a delta. Record all of these alongside the result. |
-| Peak, and why not sampling | `resource.getrusage(RUSAGE_SELF).ru_maxrss`, read **in the worker** after the response is fully delivered. The kernel maintains this high-water mark continuously, so no transient spike during JSON serialization or XLSX zip assembly can slip between samples. 50 ms sampling from a monitor thread is kept only as a **supplementary trace** for locating *where* the peak occurs; a sampled maximum is never the number reported. |
-| **No warm-up inside a measured process** | `ru_maxrss` is **monotonic for the lifetime of the process** — it cannot be reset, and any earlier peak stays in it. A warm-up request served by the same worker therefore leaves its own peak behind, and subtracting a post-warm-up baseline would not isolate the measured request (a large warm-up could even produce a false failure). So each measured run uses a **fresh worker that serves exactly one request** and is then discarded. First-request costs (lazy imports, the openpyxl module tree, cold allocator arenas) are deliberately *inside* the measurement — they are real memory the first request after a restart pays. |
-| Two runs, not two samples | Because the counter cannot be reset mid-process, the delta is taken **across two fresh-worker runs of the same build**, never within one: `baseline` = `ru_maxrss` of a freshly booted worker that has served **zero** requests; `measured` = `ru_maxrss` of a freshly booted worker that has served **exactly one** request. `delta = measured − baseline`. Both operands are absolute high-water marks of comparable processes, so the subtraction is meaningful. |
-| Optional refinement | On cgroup v2, `memory.peak` for a dedicated per-run cgroup **is** resettable (write to it), which allows a true within-process warm-up-then-measure delta. Use it if the harness has cgroup control; report which mechanism was used, since the two are not interchangeable. |
-| Absolute vs delta | Both are recorded and reported. The **delta** is the portable pass/fail target (it cancels interpreter/build differences). The **absolute** high-water mark from the measured run is what the no-OOM criterion is checked against, since a delta says nothing about total footprint. |
-| Concurrency | **1** — exactly one in-flight request, single gunicorn worker (`--workers 1 --threads 1`), no other traffic. |
-| Payload | The fixed reference payload (10 MB, ~200k rows of mixed nesting) for `/process`; a 100k-row `csv_data` body for `/export-xlsx`. Both committed as fixtures/generators so runs are reproducible. |
-| Verdict | **Pass** iff the cross-run delta `≤ 50 MiB` (`/process`) or `≤ 150 MiB` (`/export-xlsx`) **and** the measured run's absolute high-water mark stays under half the container limit (256 MiB of the default 512 MiB), as the **median of 3 run-pairs**; a single pair above a limit is retried, two of three above it is a fail. |
-| Blocked pairs are failures | A pair that cannot produce a number — OOM kill, worker crash, request timeout, truncated or incomplete response, or a missing/unreadable `ru_maxrss` — **counts as a failed pair and stays in the set of three**. It is never dropped, re-rolled as though it had not happened, or treated as a clean sample. An OOM is the single most important signal this budget exists to catch; discarding it as "no data" would invert the result. Record the failure mode with the run. |
-
-These are manual/CI-optional measurements (no perf tests gate CI in v1.2), but the numbers reported against this budget must be produced by exactly this method or they are not comparable.
-
----
-
-## 5. Design Constraints That Bound the Fixes
-
-- **No server-side payload persistence** (`MEMORY.md` 2026-05-12): the full-dataset-in-`/process`-response design must not be replaced with server-side caching/sessions for export. All fixes must respect this (compression, streaming, client-side lazy rendering are compatible; a server-side export token is not).
-- **No disk writes of payloads** (`AGENTS.md`): export buffering must not rely on OS temp files. openpyxl `write_only` mode is therefore off the table unless a documented exception (roadmap D6) is approved, and `SpooledTemporaryFile` is off the table for a different reason — at its default `max_size=0` it never rolls over and so saves no memory, while any non-zero threshold (or a `fileno()` call) puts payload bytes on disk.
-- **No frontend framework / build step**: all client fixes are vanilla JS.
-- **Strict CSP, no inline JS**: any new client code stays in `static/js/app.js`.
-- **Exact-pinned dependencies**: any new dependency (e.g. `Flask-Compress`) must be pinned exactly and added deliberately; the zero-dependency middleware is preferred.
-- **Process-local in-memory rate limiter**: `RATELIMIT_STORAGE_URI` defaults to `memory://`, whose counters are **process-local** — the effective limit is multiplied by `workers × replicas`, not by workers alone. The default deployment therefore stays at one worker and one instance; any configuration above that (roadmap 2.8/2.10) must set a shared `RATELIMIT_STORAGE_URI` (e.g. Redis). Benchmarks must record both counts and the storage backend, and assume no shared counters on `memory://`.
diff --git a/docs/plan-status-v1.2.md b/docs/plan-status-v1.2.md
new file mode 100644
index 0000000..44b6248
--- /dev/null
+++ b/docs/plan-status-v1.2.md
@@ -0,0 +1,376 @@
+# Planned Points — Consolidated Status
+
+**Date:** 2026-09-02
+**Shipped version:** `Config.APP_VERSION = '1.2.0'` (CHANGELOG entry dated 2026-08-21)
+
+The single planning document for this project. It replaces five separate files,
+which were consolidated into it and deleted:
+
+| Deleted file | What it held | Where it went |
+|---|---|---|
+| `roadmap-v1.2.md` | Phases 0–5, decisions D1–D6 | §1.3, §1.4 |
+| `security-review-v1.2.md` | Findings F1–F17 | §1.1, §2.2 |
+| `performance-review-v1.2.md` | Findings P1–P13, perf budget §4 | §1.2, §2.3, Appendix B |
+| `code-health-final.md` | 2026-05 review: top-10, quick wins, refactors | §1.5, §2.3 |
+| `export-budget-v1.2.md` | How `MAX_EXPORT_CELLS` was derived | Appendix A |
+
+**What the consolidation kept and dropped.** The appendices carry the two things
+later work has to *execute* — the export-budget measurement and the RSS protocol
+it runs under. Dropped: each finding's own location/description/effort write-up
+and the 2026-05 category scores. Those are narrative about work already shipped;
+the full text stays in git history at `065883f`, the commit before the deletion.
+
+Status is against the code in this repository, not against the CHANGELOG's own
+claims: every "Done" line below was checked against `config.py`, `routes.py`,
+`helpers.py`, `security.py`, `static/js/app.js`, `Makefile`, `.github/workflows/ci.yml`
+and `requirements*.txt`.
+
+---
+
+## Section 1 — Done
+
+### 1.1 Security findings (F1–F17)
+
+| ID | Point | Where it landed |
+|---|---|---|
+| F1 | CSV/XLSX formula injection (Critical) | `helpers.sanitize_cell` / `is_formula_trigger` for CSV/TSV/XLSX; XLSX pins `data_type='s'`; JSONL/Markdown deliberately exempt |
+| F2 | 7 dependency CVEs | Flask 3.1.3, requests 2.33.0, gunicorn 22.0.0, openpyxl 3.1.5; pytest moved out of the runtime file into `requirements-dev.txt`; `pip-audit -r requirements.txt` runs in CI |
+| F3 / F9 | Credential leakage into logs; API JSONL `ValueError` → 500 | Fixed log string with no interpolation; JSONL parse failure returns 400 |
+| F4 | User-controlled outbound header name | `routes.is_allowed_outbound_header` — strip + lowercase, then explicit allowlist |
+| F5 | Security-header gaps | HSTS on secure requests, `Permissions-Policy`, COOP, CORP; CSP gained `object-src`, `base-uri`, `frame-ancestors`, `form-action`, `upgrade-insecure-requests` |
+| F6 | SSRF: blocking DNS, no port restriction | Bounded resolver pool with admission control (`API_DNS_*`); `API_ALLOWED_PORTS` default `80,443,8443` |
+| F7 | Default SECRET_KEY accepted in production | `is_production()` fail-fast in the app factory; `env_int()` names the mistyped variable |
+| F8 | Recursion-depth DoS | `extract_table_data` depth cap; `RecursionError` → 400 `JSON nesting too deep` |
+| F10 | 413 returned HTML | JSON handlers for 413/500/404 |
+| F11 | No `Cache-Control: no-store` on data responses | `security.NO_STORE_ENDPOINTS` |
+| F12 | Rate limiting ineffective behind a proxy | Opt-in `TRUST_PROXY=1` → `ProxyFix` with exactly one hop; key derived after ProxyFix |
+| F13 | Upload extension/content-type unchecked | `routes.validate_upload` |
+| F14 | Plain-HTTP credential exposure | Docs-only remediation: HTTPS stated per deploy path; `upgrade-insecure-requests` in CSP |
+| F15 | `/health` version disclosure | Kept on by default, gated by `HEALTH_REVEAL_VERSION` |
+| F16 | Cookie hardening | `HttpOnly`, `SameSite=Lax`, `Secure` tied to `APP_ENV=production` |
+| F17 | Documentation drift | Candidates-handshake references replaced with the tree picker; MIT → GPL-3.0 |
+
+### 1.2 Performance findings (P1–P13)
+
+| ID | Point | Where it landed |
+|---|---|---|
+| P1 | Uncompressed `/process` responses | In-repo gzip middleware (D1), no new dependency; honours `Accept-Encoding` q-values; skips streamed/bodyless/already-encoded responses |
+| P2.2 / P5 | Preview mutation, unbounded nested rendering | `helpers.preview_truncate` returns a capped **copy**; client caps at 20 keys / 20 items / 500 chars |
+| P3 | XLSX fully buffered in memory (High) | Diskless normal-mode workbook + `MAX_EXPORT_CELLS` (measured, default 250 000); CSV/TSV generator-streamed and uncapped; 400 rather than truncation |
+| P4 | Eager tree-picker build | Lazy children on first toggle, per-level and total node caps |
+| P6 | No static cache headers | `STATIC_MAX_AGE` (86 400) with `?v=APP_VERSION` URLs |
+| P7 | Blocking DNS in the request path | Shared bounded resolver pool (shared with F6) |
+| P8 / P12 | Double column scan; multi-copy memory | `flatten_rows` does one pass; API path decodes the `bytearray` without an intermediate copy |
+| P9 | gunicorn timeout vs `API_FETCH_TIMEOUT` | `--timeout 60` everywhere; the invariant is now enforced at startup |
+| P10 | Dead code `find_candidate_arrays` | Removed with its four tests (D2) |
+| P11 | Hardcoded "25" preview badge | `/process` returns `preview_limit` |
+| P13 | Client-side CSV/TSV string building | Chunked Blob builders |
+
+### 1.3 Roadmap phases
+
+- **Phase 0 — Foundations.** Dependency pins, `requirements-dev.txt`, `.github/workflows/ci.yml`, `pyproject.toml` (ruff + pytest), ruff clean, GPL-3.0 correction, `autoDeployTrigger: checksPass`, dead-code removal.
+- **Phase 1 — Security.** All 15 tasks (1.1–1.15); see F-table above.
+- **Phase 2 — Performance.** All 10 tasks (2.1–2.10), including the rate-limit topology guard: `RATELIMIT_STORAGE_URI` is configurable, `WEB_CONCURRENCY` is the single source of truth for workers, `APP_REPLICAS` mirrors `numInstances`, and production refuses to start on `memory://` above one worker × one replica.
+- **Phase 3 — Refactor.** `_load_input` / `_select_table_data` extracted, `process_json` reduced, `openpyxl` imported at module top, `preview_limit` returned, type annotations added to `helpers.py` and `security.py`.
+- **Phase 4 — Features.** 4.1 load more / load all with a 50 000-row DOM guard, 4.2 row filter, 4.3 JSONL + Markdown exports, 4.4 column visibility, 4.5 `#path=` deep links, 4.7 `/health/live` + `/health/ready`, 4.8 in-page About modal and keyboard-accessible export dropdown. (4.6 was dropped with D4 — see §1.4.)
+- **Phase 5 — Docs/DX.** `MEMORY.md`, `CLAUDE.md`, `AGENTS.md`, `README.md` synced; `.env.example`; `Makefile`; `CHANGELOG.md`; version bumped to 1.2.0.
+
+### 1.4 Decisions closed
+
+| ID | Decision |
+|---|---|
+| D1 | gzip via in-repo middleware, not `Flask-Compress` |
+| D2 | `find_candidate_arrays` deleted in Phase 0, before the depth-guard work |
+| D3 | Proxy trust is opt-in via `TRUST_PROXY`, off by default |
+| D5 | Port allowlist adopted, default `80,443,8443` |
+| D6 | Exports stay diskless and memory-bounded: normal-mode workbook + measured cell budget; `write_only` and `SpooledTemporaryFile` both rejected, each on its own grounds |
+| D4 | **Declined (2026-09-02).** No Basic Auth gate. Roadmap task 4.6 and its acceptance line are dropped; per the roadmap, nothing else changes |
+
+### 1.5 Code-health review (2026-05) items now closed
+
+Top-10 issues 1, 2, 3, 4, 5, 7, 8, 9, 10 are done (CI, CVEs, dev/prod dependency
+split, ruff, `process_json` complexity, preview badge, LICENSE, `.env.example`,
+depth guard). Quick wins 1–8 are done. Larger refactors 7.1, 7.3, 7.4 and 7.5 are
+done; 7.2 is partial (see Section 2).
+
+### 1.6 Measurement work
+
+`MAX_EXPORT_CELLS = 250 000` is a measured number rather than a chosen one, derived
+by the two-fresh-process `ru_maxrss` method with a confirming point re-run at the
+shipped value. It is *indicative, not protocol-conformant*: one run-pair per shape
+through the Flask test client, where the Appendix B verdict calls for the median of
+three through a gunicorn worker. Adequate for sizing the default; not a recorded
+budget pass. Method, data and derivation: **Appendix A**.
+
+---
+
+## Section 2 — Pending / Planned
+
+### 2.1 Known limitation awaiting a decision
+
+- **JSONL export is not a faithful copy of the input document.** Roadmap 4.3 called
+  it "lossless — original values". Shipped behaviour: values are written verbatim
+  (the security-relevant half), but over the server's *flattened* projection, so
+  `{"tags": [1,2]}` exports as `"tags": "[1, 2]"` and `{"meta": {"role": "x"}}` as
+  `"meta.role": "x"`. Fixing it means shipping the original rows alongside the
+  flattened ones, doubling the payload and client memory that P2/P12 exist to
+  reduce. Explicitly flagged for a maintainer decision, not resolved either way.
+
+### 2.2 Accepted exposures, documented rather than fixed
+
+- **Unbounded DNS teardown (F6.1 / P7 residual).** `getaddrinfo` exposes no timeout
+  and cannot be cancelled. `API_DNS_TIMEOUT` bounds only the caller's wait; a pool
+  thread stays occupied until the platform resolver returns, and interpreter exit
+  can still block on it — realistically tens of seconds with glibc defaults. A
+  killable subprocess resolver is the documented escalation and remains out of v1.2
+  scope. Best-effort narrowing where the deployment allows: pin
+  `options timeout:2 attempts:1` in the container's `resolv.conf`.
+- **DNS rebinding (SSRF residual).** Mitigated by `allow_redirects=False` and
+  documented in `routes.py`. Escalation path if the threat model changes from
+  internal tool to public service: a custom `HTTPAdapter` that resolves once and
+  passes the IP with an explicit `Host` header.
+
+### 2.3 Carried-over engineering work
+
+- **Type annotations (code-health 7.2, roadmap 3.5) — partial.** `helpers.py` and
+  `security.py` are annotated. `routes.py` and `config.py` have no annotated
+  signatures, and `mypy` is not in `requirements-dev.txt`, `pyproject.toml`, the
+  `Makefile`, or CI. The roadmap deliberately marked mypy optional and skipped
+  strict mode; the remaining work is the two unannotated modules plus a mypy
+  configuration if it is wanted.
+- **Perf budget verification (Appendix B).** No row of the budget has a
+  protocol-conformant verdict. The XLSX row has an indicative measurement
+  (Appendix A) that deviates from the protocol in two ways — the Flask test client
+  instead of a gunicorn worker, and one run-pair instead of the median of three —
+  so re-running it conformantly is outstanding work, not a formality. The rest of
+  the table — `/process` transfer size ≤ 2–4 MB,
+  `/process` p95 ≤ 3 s, `/process` peak-RSS delta ≤ 50 MiB, tree-picker open
+  ≤ 500 ms on a 10 MB payload — is defined but has no recorded run. No perf test
+  gates CI (`pytest-benchmark` was deferred by decision), so these stay manual.
+- **Measurement harness is not committed.** The export-budget script is a throwaway;
+  re-deriving the budget means rebuilding it from Appendix A. Committing
+  fixtures/generators for the 10 MB reference payload and the 100 k-row `csv_data`
+  body would make the budget reproducible rather than re-derivable.
+- **Contributor docs (code-health Phase 6a/6c).** No `CONTRIBUTING.md` exists. The
+  roadmap's Phase 5 acceptance line ("a fresh contributor can set up, lint, test
+  and run coverage using only README + CONTRIBUTING-level docs") is met by the
+  README plus the `Makefile` targets, so this is a packaging question — a separate
+  file with a PR checklist — not a missing-information one.
+- **README JSON edge-case examples (code-health 6d).** Null, boolean, Unicode and
+  mixed-type arrays were to be shown as worked examples. `helpers.py` handles all
+  four and the tests cover them; the README does not illustrate them.
+- **README support line (code-health 6c, partial).** The README points readers at
+  the repository's issue tracker. The tracker exists and is enabled but holds no
+  issues; the 2026-05 review flagged the pointer as directing users nowhere useful.
+  Judgment call: keep it, or replace it with the maintainer contact.
+- **Transitive dependency drift (code-health §12).** Direct dependencies are
+  exact-pinned; transitives are not. A lock file (`pip-compile`) was noted as a
+  post-review iteration and has not been added.
+- **Docker artifacts.** `README.md` carries Dockerfile and docker-compose templates,
+  but no `Dockerfile` is checked in. Phase 5 deliberately kept these docs-only; a
+  committed Dockerfile is a fresh decision, not pending roadmap work.
+
+### 2.4 Explicitly out of scope — do not implement without a new decision
+
+These are settled exclusions, listed so they are not mistaken for a backlog:
+
+- Server-side payload caching or session storage for export — violates the
+  no-persistence requirement. Perf is served by compression, streaming and
+  client-side rendering instead.
+- Redis rate-limit storage as the default. It ships as an optional
+  `requirements-redis.txt`, required only above one worker or one replica.
+- Any frontend framework or build step.
+- Any CSP relaxation, `unsafe-inline` included. Phase 1 only tightened it.
+- Payload-level logging or telemetry.
+- Auto keep-alive pings against the Render free tier.
+- Committed `docker-compose` / systemd unit files.
+- **Any app-level authentication gate**, HTTP Basic Auth included (roadmap 4.6 / D4,
+  declined 2026-09-02). Access control stays a deployment concern — put the app
+  behind whatever the network or reverse proxy already enforces.
+
+---
+
+## Verification checklists still requiring a manual sign-off
+
+Two lines in the (now folded-in) security review's post-fix checklist are marked manual and have
+no automated equivalent: **F14** (every deployment path states HTTPS is required)
+and **F17** (no stale `candidates` or MIT references remain in the docs). The rest
+of that checklist is covered by `tests/test_routes.py`, `tests/test_security.py`
+and the Node assertions in `tests/js/`.
+
+---
+
+## Appendix A — XLSX export budget: how `MAX_EXPORT_CELLS` was measured
+
+**Measured:** 2026-08-21. **Applies to:** roadmap 2.3 / D6, finding P3.
+**Result:** `DEFAULT_MAX_EXPORT_CELLS = 250_000` cells (`config.py`).
+
+D6 requires the guard's default to be measured, not chosen. These are the numbers
+it came from, kept so it can be re-derived when the measurement is re-run.
+
+### Method
+
+Appendix B's protocol, with two documented deviations.
+
+Followed as written: `ru_maxrss` read on Linux (KiB) × 1024, reported in MiB;
+`resource.getrusage(RUSAGE_SELF).ru_maxrss` read after the response was fully
+delivered; each measured process serves **exactly one** request then exits;
+`delta = measured − baseline` across two fresh processes (baseline served zero
+requests); concurrency 1; absolute and delta both recorded; no blocked pairs
+occurred and none were discarded.
+
+**Deviations:** requests went through the Flask test client in a fresh Python
+process rather than a fresh gunicorn worker, and the sizing sweep used one
+run-pair per shape rather than the median of three. The property the protocol
+exists to protect — `ru_maxrss` is monotonic per process and cannot be reset
+mid-process — is preserved, since every number comes from a process that served
+exactly one request. These numbers are comparable to each other but must not be
+quoted against the Appendix B budget as though they came from the full
+gunicorn / median-of-three protocol.
+
+`MAX_CONTENT_LENGTH` was raised for the measurement only, so request-body size
+would not mask the workbook cost.
+
+### Data
+
+| rows × cols | cells | delta (MiB) | absolute (MiB) |
+|---|---|---|---|
+| 15,000 × 10 | 150,000 | 73.6 | 114.3 |
+| 83,333 × 3 | 249,999 | **138.9** | 179.6 |
+| 50,000 × 3 | 150,000 | **84.3** | 125.0 |
+| 20,000 × 10 | 200,000 | 98.6 | 139.2 |
+| 2,000 × 150 | 300,000 | 137.3 | 178.0 |
+| 91,666 × 3 | 274,998 | **152.2** | 193.0 |
+| 100,000 × 3 | 300,000 | **161.7** | 202.4 |
+| 40,000 × 10 | 400,000 | 195.6 | 236.3 |
+
+At equal cell counts the **narrow, tall** shape is consistently the most
+expensive (84.3 vs 73.6 MiB at 150,000 cells; 161.7 vs 137.3 at 300,000):
+openpyxl carries per-row overhead on top of per-cell. Three columns is the worst
+aspect ratio tested and the one the budget is sized against.
+
+It is also why the budget is expressed in **cells**, not rows — 50,000 rows costs
+84.3 MiB at 3 columns while 40,000 rows costs 195.6 MiB at 10, so a row count says
+almost nothing about the footprint.
+
+### Derivation
+
+Fitting the two bracketing points of the 3-column series:
+
+```text
+(150,000 cells, 84.3 MiB) and (274,998 cells, 152.2 MiB)
+slope     = 0.000543 MiB/cell
+intercept = 2.8 MiB
+150 MiB crossing = (150 − 2.8) / 0.000543 ≈ 270,900 cells
+```
+
+The 274,998-cell run measured **152.2 MiB — over the 150 MiB target** — so the
+crossing is real, not an extrapolation artifact. The budget sits at **250,000
+cells**, ~8% below the crossing, which is the margin run-to-run variance on these
+measurements needs.
+
+That value was then measured directly rather than left as a fit: 83,333 × 3 =
+249,999 cells came back at **138.9 MiB delta / 179.6 MiB absolute** (the fit
+predicted 138.6). Both numbers sit under the Appendix B thresholds — 150 MiB delta
+and the 256 MiB absolute ceiling for a 512 MiB container.
+
+**This is not a protocol-conformant pass, and must not be recorded as one.** The
+verdict in Appendix B is defined as the *median of three run-pairs* through a
+gunicorn worker; this is one run-pair through the Flask test client. The number is
+sound enough to size a default against — that is what it was collected for — but
+the `/export-xlsx` row of the budget has no conformant verdict, only an indicative
+one. See §2.3.
+
+### What the budget does and does not cover
+
+- **XLSX-only.** CSV and TSV are generator-streamed and stay uncapped, so every
+  dataset `/process` accepts remains exportable by some route. That, not an
+  unbounded XLSX path, is what keeps the export contract as wide as the input one.
+- **Enabled by default.** An unlimited default would leave P3 (High) unmitigated.
+  `MAX_EXPORT_CELLS=0` disables it for operators who knowingly opt out.
+- **Advertised, never silent.** `/process` returns `total_cells` and
+  `max_export_cells` so the client greys Excel out before the click, and
+  `/export-xlsx` returns 400 for direct API callers. No truncation — a partial
+  spreadsheet is worse than a refusal.
+- The 10 MiB request cap makes memory finite but not usefully bounded: the
+  JSON → Python → openpyxl → zip multiplier is large and data-dependent. The cell
+  budget is the bound; the request cap is not a substitute.
+
+### Reproducing
+
+The harness is not committed (throwaway script; no perf tests in CI). It does two
+things, each in its own process:
+
+1. `baseline`: boot `create_app()`, serve nothing, print `ru_maxrss`.
+2. `measured`: boot `create_app()`, POST one synthetic `csv_data` body of
+   `rows × cols` cells to `/export-xlsx` with `MAX_EXPORT_CELLS=0`, assert 200,
+   print `ru_maxrss`.
+
+Subtract. Re-derive the fit from at least two points on the narrowest aspect ratio
+you care about, and re-run a confirming point at the value you intend to ship.
+Record the new data in this appendix. Do not round the result to something tidy.
+
+---
+
+## Appendix B — Perf budget and the RSS measurement protocol
+
+Targets on a reference payload (10 MB, ~200k rows of mixed nesting), single
+free-tier worker. **No row has a protocol-conformant verdict.** The
+`/export-xlsx` row has an indicative run (Appendix A: one run-pair via the test
+client, not the median of three through gunicorn); every other row is defined but
+unmeasured. See §2.3.
+
+| Metric | Before v1.2 (est.) | Target |
+|---|---|---|
+| `/process` transfer size | ~10–20 MB | ≤ 2–4 MB (gzip) |
+| `/process` p95 latency (paste/upload only) | seconds, unbounded | ≤ 3 s |
+| Peak RSS **delta**, `/process` (10 MB input) | ~40–60 MiB | **≤ 50 MiB**, absolute high-water < 256 MiB |
+| Peak RSS **delta**, `/export-xlsx` 100k rows | hundreds of MiB (OOM risk) | **≤ 150 MiB**, absolute < 256 MiB, streams |
+| Tree-picker open, 10 MB payload | multi-second freeze | ≤ 500 ms initial, lazy children |
+| Cell with a 10k-key object | freeze | ≤ 20 keys + "more" |
+| Static assets | revalidated every load | cached ≥ 1 day |
+
+The latency target **excludes API-fetch requests** — those are bounded separately
+by `API_FETCH_TIMEOUT` plus DNS time, which would make a single aggregate p95
+meaningless. The RSS target covers the whole parse → flatten → `jsonify` pipeline;
+it is not a claim that gzip or dropping one copy fits the process under 30 MB.
+
+### Protocol (identical for both RSS rows; both are pass/fail against these rules)
+
+`ru_maxrss` is a per-process high-water mark that **cannot be reset**, which is
+what forces the fresh-process protocol.
+
+| Parameter | Definition |
+|---|---|
+| Units | `ru_maxrss` is **not portable**: KiB on Linux, **bytes** on macOS. Convert and report in **MiB**. Every threshold here is MiB, not decimal MB. Skipping the conversion reports numbers 1024× off. |
+| Environment parity | Both runs of a pair on the **same OS and kernel, container image, Python build, and cgroup limits**, on an otherwise idle host. A baseline from one image and a measurement from another is not a delta. Record all of it. |
+| Peak, not sampling | `resource.getrusage(RUSAGE_SELF).ru_maxrss`, read **in the worker** after the response is fully delivered. The kernel maintains it continuously, so no transient spike can slip between samples. 50 ms sampling is a supplementary trace for locating the peak only — never the reported number. |
+| No warm-up inside a measured process | The counter is monotonic for the process lifetime, so a warm-up request leaves its own peak behind and a post-warm-up baseline would not isolate the measured request. Each measured run uses a **fresh worker serving exactly one request**, then discarded. First-request costs (lazy imports, the openpyxl module tree, cold arenas) are deliberately inside the measurement — they are memory the first request after a restart really pays. |
+| Two runs, not two samples | `baseline` = freshly booted worker, **zero** requests served. `measured` = freshly booted worker, **exactly one**. `delta = measured − baseline`. Both are absolute high-water marks of comparable processes, so the subtraction means something. |
+| Optional refinement | On cgroup v2, `memory.peak` for a dedicated per-run cgroup **is** resettable, allowing a true within-process warm-up-then-measure delta. Report which mechanism was used; the two are not interchangeable. |
+| Absolute vs delta | Record both. The **delta** is the portable pass/fail target (it cancels interpreter/build differences); the **absolute** high-water mark is what the no-OOM criterion is checked against, since a delta says nothing about total footprint. |
+| Concurrency | **1** — one in-flight request, `--workers 1 --threads 1`, no other traffic. |
+| Payload | The fixed 10 MB / ~200k-row reference payload for `/process`; a 100k-row `csv_data` body for `/export-xlsx`. Both should be committed as fixtures so runs are reproducible (they are not — see §2.3). |
+| Verdict | **Pass** iff the cross-run delta is ≤ 50 MiB (`/process`) or ≤ 150 MiB (`/export-xlsx`) **and** the measured run's absolute high-water mark stays under half the container limit (256 MiB of 512 MiB), as the **median of 3 run-pairs**. One pair over a limit is retried; two of three over it is a fail. |
+| Blocked pairs are failures | A pair that produces no number — OOM kill, worker crash, timeout, truncated response, unreadable `ru_maxrss` — **counts as a failed pair and stays in the set of three**. Never dropped or re-rolled. An OOM is the single most important signal this budget exists to catch; discarding it as "no data" inverts the result. Record the failure mode. |
+
+These are manual measurements — no perf test gates CI — but numbers reported
+against this budget must come from exactly this method or they are not comparable.
+
+### Design constraints that bound any future fix
+
+- **No server-side payload persistence.** The full-dataset-in-`/process` design
+  must not become server-side caching or sessions for export. Compression,
+  streaming and client-side lazy rendering are compatible; an export token is not.
+- **No disk writes of payloads.** openpyxl `write_only` is off the table (it writes
+  worksheet parts to OS temp files), and `SpooledTemporaryFile` is off it for a
+  different reason: at its default `max_size=0` it never rolls over and saves no
+  memory, while any non-zero threshold — or a `fileno()` call — puts payload bytes
+  on disk. Either pointless or disk-backed, never both diskless and memory-light.
+- **No frontend framework or build step**; all client code stays vanilla in
+  `static/js/app.js`.
+- **Strict CSP, no inline JS.**
+- **Exact-pinned dependencies.** Any new one is added deliberately; the
+  zero-dependency middleware is preferred (this is why gzip is in-repo, D1).
+- **Process-local rate limiter.** `memory://` counters multiply the effective limit
+  by `workers × replicas`. Benchmarks must record both counts and the backend.
diff --git a/docs/roadmap-v1.2.md b/docs/roadmap-v1.2.md
deleted file mode 100644
index 3eba712..0000000
--- a/docs/roadmap-v1.2.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# Roadmap — v1.2.0 "Hardening & Performance" — JSON Table Converter
-
-**Date:** 2026-08-20
-**Inputs:** `docs/security-review-v1.2.md` (17 findings, F1–F17), `docs/performance-review-v1.2.md` (13 findings, P1–P13), prior `docs/code-health-final.md` (2026-05), project goals in `README.md`/`CLAUDE.md`/`AGENTS.md`/`MEMORY.md`.
-**Target:** `Config.APP_VERSION = '1.2.0'`, shipped as one milestone with zero data-persistence changes, zero CSP relaxations, zero new build tooling.
-
----
-
-## 1. Goals (recap) and How This Roadmap Serves Them
-
-| Project goal | Roadmap coverage |
-|---|---|
-| **Privacy-first, zero storage** | All fixes respect no-persistence; credential/log hygiene (F3, F9); no payload caching (P2 constraint) |
-| **Secure by default** | F1 (formula injection), F2 (CVEs), F4-F8, F10-F16 |
-| **Lightweight & fast** | P1-P9, P12 (compression, streaming, lazy rendering) |
-| **Reliable deploys** | F2 (re-audit), P9 (gunicorn timeout), Phase 0 CI gate |
-| **Internal-team usable** | Phase 4 features (load more, filter, new exports, opt-in auth) |
-| **Maintainable** | Phase 3 refactor, Phase 5 doc sync (F17), dead-code removal (P10) |
-
----
-
-## 2. Version Plan
-
-**v1.2.0** = Security hardening + performance + reliability (Phases 0-3 below) and a small set of low-risk features (Phase 4). Phases 0-3 are designed to be individually shippable; each ends green (full test suite + manual checklist).
-
-**Decision points.** D1, D2, D3, D5 and D6 are **decided** below and their dependent tasks are committed v1.2 scope. D4 is the only open item; every task and acceptance criterion that depends on it is marked *conditional (D4)* and is dropped without further impact if D4 is declined.
-
-- **D1.** gzip implementation — **decided: in-repo middleware** (~20 lines, no new pinned dependency; keeps the dep count at 7 and honors the "lean deps" value). `Flask-Compress` is the documented fallback only if the middleware cannot meet the P1 budget. (P1)
-- **D2.** `find_candidate_arrays` lifecycle — **decided: delete** (it is dead code superseded by the tree picker). Deletion happens in Phase 0, *before* the Phase 1 recursion-guard work, so guards are added only to `extract_table_data` and no guard tests for the deleted function are written. (P10/F8)
-- **D3.** Proxy-aware rate limiting — **decided: opt-in `TRUST_PROXY`/`ProxyFix`, off by default.** `X-Forwarded-For` is never trusted unless `TRUST_PROXY=1` is set; with it unset, behavior is unchanged from v1.1. (F12)
-- **D4.** Opt-in HTTP Basic Auth gate for the whole app via env (`APP_BASIC_AUTH_USER`/`APP_BASIC_AUTH_PASS`, off by default) — **OPEN, needs maintainer sign-off** before Phase 4 starts. It is the internal-tool use case from README §"Access Control" (small, opt-in, no persistence), but it *is* a new access-control surface. **Dependent scope:** task 4.6 only. If D4 is declined, drop 4.6 and its acceptance line; nothing else in v1.2 changes. (Recommendation: approve.)
-- **D5.** Port allowlist for API fetch — **decided: yes**, `API_ALLOWED_PORTS` default `80,443,8443` only. (F6.2)
-- **D6.** Export buffering vs the no-disk-writes rule: openpyxl `write_only` mode writes worksheet parts to OS temp files (transient payload-derived data). `tempfile.SpooledTemporaryFile` is not the diskless escape hatch it looks like, but not for the usual reason: with its **default `max_size=0` it never rolls over on write at all** (`_check()` tests `if max_size and tell() > max_size`, so a zero threshold is falsy) — it is then a `BytesIO` with extra indirection and **zero** memory benefit, which is the actual reason it fails to solve P3. Set a non-zero `max_size` and it *does* write payload bytes to an OS temp file once that threshold is crossed; and any call to `fileno()` (or `rollover()`) forces the disk file regardless of threshold. So it is either pointless or disk-backed — never both diskless and memory-light. Default recommendation: **diskless and memory-bounded** — a normal-mode `Workbook` writing no OS temp files, plus an **XLSX-only** `MAX_EXPORT_CELLS` budget that is **enabled by default** and sized from the measured budget in Performance Review §4 (an unlimited default would leave the High finding P3 unmitigated). The export contract stays as wide as the input contract via uncapped streaming CSV/TSV plus an advertised limit the client can see before the user clicks — not by leaving XLSX unbounded. Note the 10 MB request cap makes memory finite but not usefully bounded: the expansion multiplier is data-dependent, so the measurement sets the budget. The memory-light temp-file route only under an explicit documented exception. (P3)
-
-**Explicit production signal:** the fail-fast (1.6), `Secure` cookie (1.14) and topology-guard (2.10) behaviors are gated on **one canonical env var, `APP_ENV=production`** — never inferred from `not DEBUG`, because the documented local run `python app.py` has `DEBUG=False` by default, and never accepting a second spelling such as `PRODUCTION=true`. Two accepted names let a deployment satisfy one gate and silently miss another (e.g. passing the SECRET_KEY check while `SESSION_COOKIE_SECURE` stays off). Implement it once as `is_production()` in `config.py` and call that everywhere; test each gate through the same helper.
-
----
-
-## 3. Phases
-
-### Phase 0 — Foundations: Dependencies, CI, Tooling  (≈ 0.5 day)
-
-**Goal:** eliminate known CVEs, stop test tooling reaching production, add a CI gate before the auto-deploy (`render.yaml` deploys every push with zero checks today).
-
-| # | Task | Files | Fixes |
-|---|---|---|---|
-| 0.1 | Pin upgrades: `Flask==3.1.3`, `requests==2.33.0`, `gunicorn==22.0.0`, `openpyxl==3.1.5` | `requirements.txt` | F2 |
-| 0.2 | Move `pytest==9.0.3` to new `requirements-dev.txt` (`-r requirements.txt` + pytest, ruff, coverage, pip-audit) | `requirements-dev.txt` (new) | F2 |
-| 0.3 | Add `.github/workflows/ci.yml`: install dev deps → `ruff check .` → `ruff format --check .` → `python -m pytest tests/ -v` → `pip-audit -r requirements.txt` | `.github/workflows/ci.yml` (new) | F2 |
-| 0.4 | Add `pyproject.toml` (ruff + pytest config, `target-version = "py311"`, line-length 100) | `pyproject.toml` (new) | — |
-| 0.5 | Run `ruff check . --fix`; fix remaining warnings manually; verify format | all `.py` | — |
-| 0.6 | License consistency: README/CLAUDE badge "MIT" → GPL-3.0 (LICENSE file is GPL-3.0) | `README.md`, `CLAUDE.md` | F17 |
-| 0.7 | Set `autoDeployTrigger: checksPass` in `render.yaml` (replaces `autoDeploy: true`) so Render waits for CI checks and blocks deployment when checks fail or are missing | `render.yaml` | — |
-| 0.8 | Remove dead code `find_candidate_arrays` + its 4 tests (D2); update the stale candidates-handshake references in `MEMORY.md`/`CLAUDE.md`/`AGENTS.md` | `helpers.py`, `tests/test_helpers.py`, docs | P10, F8 |
-
-**Acceptance:** `pip-audit -r requirements.txt` = 0 vulnerabilities; CI green; **`python -m pytest tests/ -v` exits 0** after the upgrades — the passing command, not a fixed count, is the criterion, because 0.8 deliberately removes the four `find_candidate_arrays` tests (baseline **82 → 78**); `pip install -r requirements.txt` no longer installs pytest; `render.yaml` gates deploys on CI checks; `find_candidate_arrays` and its tests are gone.
-
----
-
-### Phase 1 — Security Hardening  (≈ 1.5-2 days)
-
-**Goal:** close every open security finding (F15 is aligned with the existing `/health` contract, not deferred).
-
-| # | Task | Files | Fixes |
-|---|---|---|---|
-| 1.1 | **Formula-injection sanitization (spreadsheet formats only)**: `sanitize_cell(value)` in `helpers.py` for CSV/TSV/XLSX (triggers `= + - @`, tab, CR, LF — per-format policy in Security Review F1); apply in `export_csv`, `export_xlsx` (replace duplicated `isinstance(v,(dict,list))` branches), and in `app.js` `downloadDelimited()` escape. JSONL (4.3) stays lossless; Markdown (4.3) uses Markdown escaping — neither gets formula sanitization. Tests: `=SUM(A1)`, `@cmd`, `+1`, `-1`, tab/CR/LF-prefixed on all four export paths (2 server routes + client CSV + client TSV) | `helpers.py`, `routes.py`, `static/js/app.js`, `tests/test_routes.py` | **F1** |
-| 1.2 | **Log hygiene**: fixed message `logger.warning('API request failed')` — never log the URL (query, fragment, userinfo, and path can all carry tokens); `caplog` assertions that no URL component or token reaches logs | `routes.py`, `tests/test_routes.py` | F3, F9 |
-| 1.3 | **API-fetch JSONL ValueError → 400** generic message (before outer handler); keeps the exception out of logs and returns the correct client-error status | `routes.py`, `tests/test_routes.py` | F9 |
-| 1.4 | **Outbound header-name allowlist (a real allowlist, case-insensitively matched)**: the token regex `^[A-Za-z0-9-]+$` plus a reserved-name blocklist is a **denylist** — anything not on the list passes, and since HTTP field names are case-insensitive, `Host`, `PROXY-AUTHORIZATION` or `Cookie` slip past a lowercase membership test. Instead: normalize with `name.lower()` (and strip surrounding whitespace) **before** any comparison, then accept only names in an explicit permitted set (e.g. `accept`, `accept-language`, `authorization` where the auth UI supplies it, `user-agent`, `x-api-key`, plus any documented additions); everything else → 400. Keep the token regex as a syntax check on top, not as the authorization decision. Tests: mixed-case `Host`, `Proxy-Authorization`, `CoNnEcTiOn`, a leading/trailing-space variant, and one permitted header in unusual case | `routes.py`, `tests/test_routes.py` | F4 |
-| 1.5 | **Header hardening**: add HSTS (secure requests only), `Permissions-Policy`, `Cross-Origin-Opener-Policy`, `Cross-Origin-Resource-Policy`; extend CSP with `object-src 'none'; base-uri 'self'; frame-ancestors 'none'; form-action 'self'` (build directives as a list or keep the trailing `;` separator — see Security Review F5); keep `X-Frame-Options: DENY` | `security.py`, `tests/test_routes.py` | F5 |
-| 1.6 | **SECRET_KEY fail-fast**: `create_app` raises when `APP_ENV=production` is set and `SECRET_KEY` is the dev default/unset (explicit production signal — not `not DEBUG`, which would block the documented local run); env-var int validation with clear messages | `app.py`, `config.py`, `tests/test_routes.py` | F7 |
-| 1.7 | **Recursion-depth guard**: `_depth`/`max_depth` on `extract_table_data` (mirror `flatten_for_csv`); `find_candidate_arrays` is removed in Phase 0 (D2), so no guard or tests for it; wrap `json.loads`/`parse_jsonl` callers to catch `RecursionError` → 400 "JSON nesting too deep"; 1500-deep nesting test | `helpers.py`, `routes.py`, `tests/test_helpers.py`, `tests/test_routes.py` | F8 |
-| 1.8 | **Bounded DNS admission**: shared, per-process `ThreadPoolExecutor` (fixed `max_workers`, e.g. 4), created **lazily inside the worker after fork** (module-level lazy init under a lock, or `os.register_at_fork(after_in_child=...)`). **Teardown is documented, not guaranteed:** `shutdown(wait=False, cancel_futures=True)` returns immediately but cannot cancel a running `getaddrinfo`, and `concurrent.futures` joins its non-daemon threads at interpreter exit regardless of `wait`, so worker recycling **can block for up to the remaining lookup time**. **Decided for v1.2: accept and document that teardown is *not* bounded by anything this code controls.** `getaddrinfo` exposes no timeout, so the wait is whatever the platform resolver takes: glibc's defaults are ~5s per nameserver with 2 attempts, tried across every nameserver in `resolv.conf`, so the realistic worst case is **tens of seconds**, not ≤ 5s — and it is only bounded at all if `options timeout:N attempts:M` are actually set. v1.2 therefore ships **no guaranteed bounded teardown**; it documents the exposure and, where the deployment allows, pins `options timeout:2 attempts:1` in the container's `resolv.conf` as a best-effort narrowing. A killable subprocess resolver is the only real bound and stays the documented escalation, not v1.2 scope. Do not describe the teardown as bounded in any doc or comment. `API_DNS_TIMEOUT` (default 3s) bounds **only `Future.result()`** — it cannot cancel a running `getaddrinfo`, so an in-flight **semaphore permit is acquired before submit and released from the future's done-callback**, never on caller timeout (equivalently: a bounded submission queue). When no permit is available within a short admission wait, return 503/400 rather than queueing unboundedly. Tests: repeated timeouts do not leak permits or threads, saturation returns the admission error instead of blocking, and the lifecycle test asserts the *accepted* recycling behavior — shutdown may wait on an in-flight lookup for as long as the platform resolver takes — rather than a non-blocking exit or any bound this code enforces | `security.py`, `config.py`, `tests/test_security.py` | F6.1, P7 |
-| 1.9 | **Port allowlist** for API fetch (D5): `API_ALLOWED_PORTS` default `80,443,8443` | `security.py`/`routes.py`, `config.py`, tests | F6.2 |
-| 1.10 | **Proxy-aware rate limiting** (D3): `TRUST_PROXY=1` → `ProxyFix(app, x_for=1, x_proto=1, x_host=1)` (exact trusted hop count); rate-limit key derived from `request.remote_addr` *after* ProxyFix — never from the raw `X-Forwarded-For` header; forged-header and multi-proxy tests; document Redis storage for multi-instance in `MEMORY.md` | `app.py`, `extensions.py`, `config.py`, tests | F12 |
-| 1.11 | **JSON error handlers**: 413 → `{"error": "Request too large (max 10MB)"}` JSON; generic 500 → JSON | `app.py`, tests | F10 |
-| 1.12 | **`Cache-Control: no-store`** on `/process`, `/export-csv`, `/export-xlsx`, `/health` | `security.py` or routes, tests | F11 |
-| 1.13 | **Upload validation**: reject non-`.json`/`.jsonl` filenames and unexpected content-types → 400 | `routes.py`, tests | F13 |
-| 1.14 | **Cookie hardening**: `SESSION_COOKIE_HTTPONLY=True`, `SESSION_COOKIE_SAMESITE='Lax'`, `SESSION_COOKIE_SECURE` tied to the explicit `APP_ENV=production` signal (not `not DEBUG`) | `config.py`, tests | F16 |
-| 1.15 | **Version disclosure** (aligned with the current `/health` contract): keep `version` returned by default; optional `HEALTH_REVEAL_VERSION` gate defaults to **on** (no behavior change); add tests only if the gate is implemented | `routes.py`, `config.py` | F15 |
-
-**Acceptance:** Security Review §4 checklist fully passes (formula files open inert in Excel; SSRF battery incl. decimal/hex/mapped-IPv6; CSRF 400 without token; no token in `caplog`; HSTS+CSP headers present; 413/500 JSON; depth-1500 JSON → 400; per-client rate buckets with `TRUST_PROXY=1`).
-
----
-
-### Phase 2 — Performance  (≈ 1.5-2 days)
-
-**Goal:** meet the perf budget in Performance Review §4.
-
-| # | Task | Files | Fixes |
-|---|---|---|---|
-| 2.1 | **gzip middleware** (D1): compress JSON/text bodies >1 KB when client accepts gzip; set `Content-Encoding: gzip`, `Vary: Accept-Encoding`; skip bodyless/`HEAD`/`204`/`304`/already-encoded/streamed (`response.is_streamed`) responses; remove or recompute `Content-Length` | `app.py` (or `security.py`), tests | P1 |
-| 2.2 | **Static cache headers**: `SEND_FILE_MAX_AGE_DEFAULT=86400` + `?v=APP_VERSION` on CSS/JS URLs | `config.py`, `templates/index.html` | P6 |
-| 2.3 | **Diskless, memory-bounded exports** (D6): normal-mode `Workbook` + an XLSX-only `MAX_EXPORT_CELLS` budget → 400 instead of OOM; no OS temp files (openpyxl `write_only` writes them; `SpooledTemporaryFile` is excluded on its own merits — see D6 — since `max_size=0` never rolls over and saves nothing, while a non-zero threshold or a `fileno()` call writes payload bytes to disk); no `output.getvalue()`; CSV/TSV stay **uncapped** via a generator response (natively streamable). The guard is **enabled by default** — an unlimited default would leave P3 (High) unmitigated — and is budgeted in **cells** (`rows × columns`, what actually drives openpyxl memory), with the default derived from the Performance Review §4 measurement rather than chosen by feel. Response contract is **additive**: reuse the existing `total_rows` (`routes.py:192`) and add `total_cells` + `max_export_cells`; the client greys out Excel iff `max_export_cells > 0 && total_cells > max_export_cells` and points at CSV/TSV, and `/export-xlsx` independently returns 400 `{"error": "…cells exceeds the Excel export limit…; use CSV/TSV"}`. Uncapped CSV/TSV — not an uncapped XLSX path — is what keeps the export contract as wide as the input contract (see Performance Review P3) | `routes.py`, `config.py`, `static/js/app.js`, tests | P3 |
-| 2.4 | **Preview truncation (non-mutating)**: build a separate preview projection (copy) capping long strings / nested arrays / nested objects; `table_data`/`csv_data` keep full fidelity — test that exports stay untruncated | `routes.py`, `helpers.py`, tests | P2.2, P5 |
-| 2.5 | **Lazy tree picker**: build children on first toggle; cap per-level children and total nodes | `static/js/app.js` | P4 |
-| 2.6 | **Client render caps**: `renderNestedObject` ≤ 20 keys + "more"; `formatValue` stringify cap for primitive arrays; long-string truncation | `static/js/app.js` | P5 |
-| 2.7 | **Memory trim**: decode `bytearray` directly (drop `bytes()` copy) in API-fetch; single-pass flatten + column accumulation (collect into a set, sort once — preserves current column order) | `routes.py`, `helpers.py`, tests | P12, P8 |
-| 2.8 | **gunicorn tuning**: `--timeout 60` everywhere (`render.yaml`, README, Docker/systemd snippets); document the `API_FETCH_TIMEOUT < gunicorn timeout` invariant. **Deployment topology is coupled to rate-limit storage (see 2.10): one worker *and* one instance stays the default whenever `RATELIMIT_STORAGE_URI` is `memory://`**; `--workers 2`, the README's three `--workers 4` examples (`README.md:189`, `:207`, `:256`), and any `numInstances > 1` require shared storage first | `render.yaml`, `README.md` | P9 |
-| 2.9 | **Chunked Blob** for client CSV/TSV | `static/js/app.js` | P13 |
-| 2.10 | **Rate-limit storage matches the deployment topology.** `memory://` counters are process-local, so the effective limit is multiplied by **`workers × replicas`**, not workers alone. Four parts, in order: **(a) make storage configurable at all** — `config.py:21` currently *hardcodes* `RATELIMIT_STORAGE_URI = 'memory://'`, so no deployment can set shared storage today; read it from the environment first. **(b) One source of truth for the worker count** — do not let a declared value drift from reality: define `WEB_CONCURRENCY` as the single source and make every start command derive from it (`gunicorn … --workers "$WEB_CONCURRENCY"`), so the number the app reads and the number gunicorn runs cannot disagree; a bare `--workers N` in a command with a different declared value is the failure mode to design out. Replica count is invisible to the process, so `APP_REPLICAS` is enforced at the deployment layer and must mirror `render.yaml`'s `numInstances`. **(c) Fail closed, not open** — defaults of `1` make the guard useless exactly where it matters, since an undeclared 4-worker deployment looks single-worker. Under `APP_ENV=production` both values must be **explicitly declared**: missing, unparseable, or inconsistent-with-the-start-command declarations are a startup error, and shared storage is *required* whenever either count is greater than one **or cannot be verified**. Outside production the defaults stay. **(d) Fix the deployment surface** — the three README/Docker/systemd `--workers 4` examples (`README.md:189`, `:207`, `:256`) and `render.yaml` (which sets neither the variables nor `--workers`); document `RATELIMIT_STORAGE_URI=redis://…` as the supported multi-process setup — **and add the client it needs**: Flask-Limiter's Redis backend requires the optional `redis` package (via `limits[redis]`), which is absent from `requirements.txt`, so the prescribed production configuration would fail at limiter initialization. Add an exact-pinned `redis==<version>` (or `limits[redis]`) in Phase 0.1 alongside the other pins, or pick a shared backend whose driver already ships. Tests: two limiter instances on `memory://` do **not** share counters (the multiplier is real); the guard warns outside production; it raises under `APP_ENV=production` for a missing declaration, for a declaration that contradicts the start command, and for topology > 1 on `memory://` | `app.py`, `extensions.py`, `config.py`, `README.md`, `render.yaml`, tests | F12 |
-
-**Acceptance:** Performance Review §4 budget met on the reference payload; export of 100k rows completes without OOM; tree picker opens instantly on a 10 MB payload; perf regression spot-checked manually (no automated perf tests in CI — optional `pytest-benchmark` deferred).
-
----
-
-### Phase 3 — Refactor & Correctness  (≈ 1 day)
-
-**Goal:** reduce `process_json` complexity (cyclomatic ≈ 15), eliminate known correctness nits. Carries forward the unimplemented recommendations from `docs/code-health-final.md` §4.1/§4.3/§7. (Dead-code removal for `find_candidate_arrays` is already done in Phase 0.)
-
-| # | Task | Files | Fixes |
-|---|---|---|---|
-| 3.1 | Extract `_load_input(request, data_format) -> (data, error_response)` (file/paste/api) and `_select_table_data(data, path) -> (rows, error_response)`; `process_json` body ≤ ~50 lines | `routes.py`, tests | — |
-| 3.2 | **No new extraction — consolidation only.** Both helpers are *created in the phase that first needs them*, not here: `serialize_cell_value(v)` lands in **1.1** (formula sanitization) and `preview_truncate(row)` in **2.4** (preview projection), each in `helpers.py` with its own tests. Phase 3 then only tidies them (signatures, type hints, docstrings, de-duplicating any call-site logic). This removes the ordering cycle where 1.1 and 2.4 depended on a helper scheduled for a later phase | `helpers.py` | — |
-| 3.3 | Return `preview_limit` in `/process` payload; use it for the badge; note sort-scope in UI text | `routes.py`, `static/js/app.js` | P11 |
-| 3.4 | Move `openpyxl` import to module top (fails fast on missing dep) | `routes.py` | — |
-| 3.5 | Type annotations on `helpers.py`/`security.py` signatures (mypy optional; skip strict mode to limit scope) | `helpers.py`, `security.py` | — |
-
-**Acceptance:** `python -m pytest tests/ -v` exits 0 with the remaining tests unchanged (the post-0.8 baseline of 78, plus everything added in Phases 1–2); `process_json` ≤ 50 lines; badge reflects config; **no breaking behavior change** for API consumers — the response gains keys (`preview_limit`, `total_cells`, `max_export_cells`) but no existing key changes name, type, or meaning.
-
----
-
-### Phase 4 — Features (v1.2 scope, all client-side / opt-in)  (≈ 2-3 days)
-
-**Goal:** features that use data already available client-side (respecting no-persistence) plus the opt-in internal-team access gate. Anything needing server-side storage is explicitly out of scope (see §5).
-
-| # | Feature | Files | Notes |
-|---|---|---|---|
-| 4.1 | **Load more / pagination**: since `csv_data` is already in the browser, add "Load next 500" / "Load all" over the full dataset with a row-count warning (freeze guard at ~50k DOM rows) | `static/js/app.js`, `templates/index.html` | Serves P2.3 and fixes the sort-only-preview quirk (full-dataset client sort once loaded) |
-| 4.2 | **Row filter/search**: case-insensitive substring filter across visible/full data | `static/js/app.js` | Pure client-side |
-| 4.3 | **New client-side exports**: JSONL (lossless — original values, **no** formula sanitization) and Markdown table (Markdown-specific escaping only; the spreadsheet sanitizer from 1.1 does not apply) per `MEMORY.md` guidance | `static/js/app.js`, `templates/index.html` | Dropdown additions |
-| 4.4 | **Column visibility toggle** (hide/show columns in preview) | `static/js/app.js`, `static/css/style.css`, `templates/index.html` | |
-| 4.5 | **Deep-linkable path selection** (`#path=users.0.orders` pre-fills the tree selection) | `static/js/app.js` | Small UX win for repeat conversions |
-| 4.6 | **Opt-in Basic Auth gate** — *conditional (D4), implement only if approved*: `APP_BASIC_AUTH_USER/PASS` env → `before_request` 401 (constant-time compare, `WWW-Authenticate`); off by default | `app.py`, `config.py`, `security.py`, `render.yaml` comment | Internal-tool goal; no persistence |
-| 4.7 | **`/health` split**: `/health/live` (process) + `/health/ready` (deps/limits) for Render health checks | `routes.py` | Small ops win |
-| 4.8 | Replace `alert()` About dialog with in-page modal (also fixes the hardcoded v1.1.0 string); make export dropdown keyboard-accessible (`aria-expanded`, Escape) | `static/js/app.js`, `templates/index.html`, `static/css/style.css` | From `code-health-final.md` §4.10 |
-
-**Acceptance:** manual pass of each *in-scope* feature; all exports include full row counts (not just 25); no new dependencies; CSP intact (no inline JS); `alert()` removed. **Conditional (D4):** if and only if D4 is approved, the Basic Auth gate rejects unauthenticated requests with 401 when the env vars are set and is fully transparent when they are unset; if D4 is declined this criterion does not apply.
-
----
-
-### Phase 5 — Docs, Memory, DX  (≈ 0.5 day)
-
-| # | Task | Files |
-|---|---|---|
-| 5.1 | Sync `MEMORY.md`: multi-array handshake entry → tree-picker handshake; add entries for formula injection, fixed API-fetch log message (no URL), ProxyFix/TRUST_PROXY, DNS timeout, gunicorn timeout invariant, port allowlist | `MEMORY.md` |
-| 5.2 | Sync `CLAUDE.md` + `AGENTS.md` (project snapshot: `/process` response shape, preview_limit, exports, license) | `CLAUDE.md`, `AGENTS.md` |
-| 5.3 | `README.md`: license badge (GPL-3.0), new env vars table rows, HTTPS-required note per deploy path, perf notes | `README.md` |
-| 5.4 | Add `.env.example` (all vars, safe placeholders) and `Makefile` (`test`, `lint`, `format`, `audit`, `coverage`) | `.env.example`, `Makefile` (new) |
-| 5.5 | `CHANGELOG.md` starting at 1.1.0; bump `APP_VERSION='1.2.0'` | `CHANGELOG.md` (new), `config.py`, `static/js/app.js` (About text) |
-
-**Acceptance:** a fresh contributor can set up, lint, test, and run coverage using only README + CONTRIBUTING-level docs; no stale candidates/MIT references remain.
-
----
-
-## 4. Effort Summary & Suggested Sequencing
-
-| Phase | Effort | Depends on | Shippable alone? |
-|---|---|---|---|
-| 0 Foundations | 0.5 day | — | Yes |
-| 1 Security | 1.5-2 days | Phase 0 (clean base) | Yes |
-| 2 Performance | 1.5-2 days | Phase 0 (and F1 for export changes) | Yes |
-| 3 Refactor | 1 day | Phases 1 & 2 — both helpers are *created* there (1.1, 2.4); Phase 3 only consolidates them | Yes |
-| 4 Features | 2-3 days | Phase 2 (lazy render, caps) | Yes |
-| 5 Docs/DX | 0.5 day | all (doc accuracy) | Yes |
-
-**Total: ≈ 7-9 days** (single engineer, including test updates and the manual verification checklists).
-
-**Risk order:** Phase 0 first (deploying with gunicorn 21.2.0 while knowing about CVE-2024-1135 is the standing exposure), then Phase 1.1 (formula injection) before any further feature work on exports. Phase 3 (refactor) intentionally follows Phase 2 (performance); both touch `routes.py`/`helpers.py`, so keep each phase's commits scoped per file. Do not assume a refactored `process_json` exists during Phase 2 — Phase 2 works against the current structure, and the 3.1/3.2 helper extractions land in Phase 3.
-
----
-
-## 5. Explicitly Out of Scope (do not implement without a decision)
-
-- **Server-side payload caching/session storage for export** — violates the no-persistence hard requirement (`MEMORY.md` 2026-05-12). Perf is solved via compression + streaming + client-side rendering instead.
-- **Redis rate-limit storage by default** — the default stays `memory://` with a **single worker and a single instance** (see 2.10). Redis (or any shared `RATELIMIT_STORAGE_URI`) becomes *required*, not optional, as soon as more than one worker or instance is run; v1.2 ships the guard-rail and the docs, not a bundled Redis dependency.
-- **Frontend framework / build step** — forbidden by project conventions.
-- **CSP relaxation** (e.g. `unsafe-inline`) — never; Phase 1 only *tightens* CSP.
-- **Payload-level logging / telemetry** — never; Phases 1.2/1.3 are about *removing* such leaks.
-- **Auto-keep-alive pings** — defeats Render free-tier cost model.
-- **`docker-compose`/systemd file additions** — docs only in Phase 5.
-
----
-
-## 6. Definition of Done (v1.2.0)
-
-- [ ] `python -m pytest tests/ -v` exits 0 (the command is the criterion, not a count). Baseline for v1.2 is the **78** tests remaining after Phase 0.8 removes the four `find_candidate_arrays` tests (82 − 4), plus every test added in Phases 1–5.
-- [ ] `pip-audit -r requirements.txt` → 0 vulnerabilities; CI (Phase 0.3) green on push/PR.
-- [ ] Rate limiting is coherent with the shipped topology: the default deployment runs one worker and one instance on `memory://`, every multi-worker or multi-instance example in the docs sets a shared `RATELIMIT_STORAGE_URI`, and the declared-topology guard fires (Phase 2.10).
-- [ ] `ruff check .` and `ruff format --check .` exit 0.
-- [ ] Security Review §4 checklist passes (formula injection inert, SSRF battery, log hygiene via caplog, headers, fail-fast SECRET_KEY, depth guards, JSON error handlers, no-store, proxy-aware limiting).
-- [ ] Performance Review §4 budget met on the reference payload; 100k-row XLSX export does not OOM.
-- [ ] All three input methods × both formats × all auth methods work end-to-end; multi-array JSON triggers the tree picker; picking a path returns rows.
-- [ ] All exports download full row counts; Markdown/JSONL exports added; `alert()` removed.
-- [ ] `GET /health` returns `{"status":"ok","version":"1.2.0"}`; `/health/live` + `/health/ready` present.
-- [ ] `MEMORY.md`/`CLAUDE.md`/`AGENTS.md`/`README.md` describe the tree-picker handshake, GPL-3.0 license, and all new env vars.
-- [ ] No new file writes, DB calls, payload logging, inline JS/CSS, or CSP relaxations introduced.
diff --git a/docs/security-review-v1.2.md b/docs/security-review-v1.2.md
deleted file mode 100644
index 7a12951..0000000
--- a/docs/security-review-v1.2.md
+++ /dev/null
@@ -1,350 +0,0 @@
-# Security Review — JSON Table Converter (v1.2 planning)
-
-**Date:** 2026-08-20
-**Scope:** `app.py`, `config.py`, `extensions.py`, `security.py`, `helpers.py`, `routes.py`, `templates/index.html`, `static/js/app.js`, `requirements.txt`, `render.yaml`, deployment docs
-**Method:** Manual source audit + standard-library probing of SSRF edge cases (`urlparse`/`getaddrinfo`/`ipaddress`). Full `pip-audit`/pytest could not be re-run in this sandbox (no pip); the dependency findings below were originally confirmed by `pip-audit` in `docs/code-health-final.md` (2026-05-02) and the pins are unchanged since.
-**Threat model:** Unauthenticated, internet-facing web service (Render free tier, no persistence, no auth). Attacker can submit arbitrary JSON/JSONL via paste/file and arbitrary URLs via the API-fetch feature.
-
----
-
-## 1. Executive Summary
-
-The application has a strong security posture for its size: mandatory CSRF, SSRF pre-validation with `allow_redirects=False`, strict CSP with no inline scripts, consistent `escapeHtml()` on all dynamic frontend rendering, generic error messages, and deliberate no-storage/no-payload-logging. Those fundamentals are solid and must be preserved.
-
-However, the audit found **1 Critical, 2 High, and 8 Medium** issues that should be addressed in the next version. The most serious is **CSV/Excel formula injection (CWE-1236)** — the core feature of this tool (converting untrusted API/file JSON into spreadsheet files) actively enables it. The second most urgent is the **unpatched dependency set** (`gunicorn 21.2.0` carries a High-severity HTTP request-smuggling CVE). Several smaller issues (credential leakage in error logs, user-controlled outbound header names, missing hardening headers, DNS-lookup DoS, no SECRET_KEY fail-fast) are cheap to fix.
-
-| Severity | Count | Items |
-|---|---|---|
-| Critical | 1 | F1 CSV/Excel formula injection |
-| High | 2 | F2 Dependency CVEs (gunicorn smuggling), F12 Rate limiting ineffective behind proxy |
-| Medium | 8 | F3 Credential leak in error logs, F4 User-controlled outbound header name, F5 Security-header gaps + no HSTS, F6 SSRF gaps (slow DNS, open ports, residual rebinding), F7 Default SECRET_KEY no fail-fast, F8 Recursion-depth DoS, F9 API JSONL → 500 + log leakage, F11 Missing no-store cache control |
-| Low | 5 | F10 413 handled by HTML, F13 Upload validation, F14 Credentials over plain HTTP (deploy guidance), F15 `/health` version disclosure, F16 JWT/CSRF session cookie flags |
-| Info | 1 | F17 Documentation drift (MIT vs GPL, stale candidates handshake) |
-
-**Quick wins (≤1h each):** F4, F5, F7, F9, F10, F11, F15.
-**Must-do before next deploy:** F1, F2.
-
----
-
-## 2. Findings
-
-### F1 — CSV / Excel formula injection (CWE-1236) — **Critical**
-
-**Location:** `routes.py:217-238` (`export_csv`), `routes.py:262-277` (`export_xlsx`), `static/js/app.js:482-513` (`downloadDelimited`).
-
-**Description:** Cell values beginning with `=`, `+`, `-`, or `@` are written verbatim into CSV/TSV/XLSX output. When the exported file is opened in Excel/LibreOffice, those values are evaluated as formulas (e.g. `=HYPERLINK("http://evil.example","click")`, `=cmd|' /C calc'!A0`, `=1+1`). The app's core workflow is converting *untrusted* API responses and file uploads into spreadsheets — an attacker who controls any cell value controls the exported file's formulas.
-
-For XLSX this is confirmed behavior of `openpyxl` (3.1.2): a string value starting with `=` is serialized as a formula cell, not a string. Both the server-side CSV path (`csv.DictWriter`) and the client-side CSV/TSV path write the raw string.
-
-**Exploitation:** User (or automated pipeline) converts `[{"name": "=HYPERLINK(\"https://evil.example/\",\"click\")"}]` and exports CSV or XLSX; opening the file in Excel triggers the formula → credential/CSV exfiltration or malware download. The XLSX path is worse because Excel formulas run without the "formula in CSV" warning.
-
-**Remediation (format-specific):** Sanitize cell values in the spreadsheet-compatible export paths (server CSV, server XLSX, client CSV, client TSV). If a value begins with `=`, `+`, `-`, `@`, tab, CR, or LF (all are formula triggers per OWASP), force it to be treated as text. Choose one *tested* policy per format — OWASP warns that naive single-quote prefixing can be stripped when Excel saves and reopens the file, so verify the round-trip:
-- **CSV/TSV (server + client):** prefix dangerous values with a single quote `'` (or a leading tab) and add an acceptance test that opens the file after an Excel save/reopen round-trip.
-- **XLSX:** write dangerous strings explicitly as string cells (do not let openpyxl infer a formula); assert the cell's `data_type` is `'s'`.
-- **JSONL / Markdown exports (roadmap 4.3) must NOT be formula-sanitized:** JSONL stays lossless; Markdown uses Markdown-specific escaping.
-
-Centralize in one helper on each side:
-- Backend: `sanitize_cell(value)` in `helpers.py`, used by both `export_csv` and `export_xlsx` (replaces the duplicated `isinstance(v, (dict, list))` branches — see roadmap refactor).
-- Frontend: sanitize inside `downloadDelimited()`'s `escape()`. The preview may render raw text, but every export path must sanitize.
-
-**Effort:** 1-2h. **Tests (automated, all four export paths):** extend `tests/test_routes.py` with `=SUM(A1)`, `@cmd`, `+1`, `-1`, and tab-/CR-/LF-prefixed values for both `export_csv` and `export_xlsx`, asserting the generated output; for the client paths, extract the sanitizer into a pure function in `app.js` and exercise `downloadDelimited()` with both delimiters (`','` and `'\t'`) via a Node-based assertion script (or a documented browser manual check if Node is not available in CI). Two export paths must not be able to regress while the checklist still passes.
-
----
-
-### F2 — Unpatched dependency vulnerabilities — **High**
-
-**Location:** `requirements.txt` (all pins unchanged since 2026-05 audit).
-
-**Description:** `pip-audit` in `docs/code-health-final.md` reported 7 known CVEs; the pins are still old:
-
-| Package | Pin | CVE(s) | Fix |
-|---|---|---|---|
-| `gunicorn` | `21.2.0` | CVE-2024-1135 (**High**, HTTP request smuggling), CVE-2024-6827 | `22.0.0` |
-| `requests` | `2.31.0` | CVE-2024-35195, CVE-2024-47081, CVE-2026-25645 | `2.33.0` |
-| `Flask` | `3.0.0` | CVE-2026-27205 | `3.1.3` |
-| `pytest` | `7.4.4` | CVE-2025-71176 (test-only) | `9.0.3` |
-| `openpyxl` | `3.1.2` | `datetime.utcnow()` DeprecationWarning (informational) | `3.1.5` |
-
-**Impact:** gunicorn request smuggling is reachable only when combined with a front proxy that de-duplicates Content-Length/Transfer-Encoding differently than gunicorn — precisely the Render/Nginx deployment described in the README.
-
-**Remediation (roadmap Phase 0):**
-- `requirements.txt`: `Flask==3.1.3`, `requests==2.33.0`, `gunicorn==22.0.0`, `openpyxl==3.1.5`.
-- Move `pytest==9.0.3` (and future `ruff`, `coverage`, `pip-audit`) into a new `requirements-dev.txt`.
-- Re-run `pip-audit -r requirements.txt` at implementation time (newer fixes may exist) and pin exactly.
-- Keep "exact pins + dedicated bump commit + full test suite" convention from `MEMORY.md`.
-
-**Effort:** 30-60m + full test pass. **Risk:** Flask 3.1 deprecates nothing used here; verify `WTF_CSRF_ENABLED` and limiter behavior in tests.
-
-**Reachability note:** CVE-2026-25645 (requests, GHSA-gc5v-m9x4-r6x2) affects only `requests.utils.extract_zipped_paths()`, which this app never calls — the upstream advisory states standard `requests` usage is unaffected. It is counted here as package/supply-chain hygiene, not a reachable runtime risk. All fix versions in the table are *minimum* patched versions; re-run `pip-audit` at implementation time in case newer pins are preferred.
-
----
-
-### F3 — Credential leakage into server logs (query-param auth) — **Medium**
-
-**Location:** `routes.py:148` — `logger.warning('API request failed: %s', e)`.
-
-**Description:** When the connection fails, `requests` exception messages include the **full URL including query string**. With `auth_method == 'query_param'` (routes.py:105-109) the token rides in the URL, so `logger.warning(...)` writes the secret into stdout logs — a direct violation of the "no payload logging / no credential logging" stance. Example message: `HTTPConnectionPool(host='api.example.com', port=443): Max retries exceeded with url: /data?api_key=SECRET ...`.
-
-**Remediation:** Log a fixed message with no user-controlled data:
-
-```python
-except requests.exceptions.RequestException:
-    logger.warning('API request failed')
-```
-
-Do not log the URL at all — query strings, fragments, userinfo, *and paths* can all carry tokens, so a redaction helper that preserves the path is not sufficient. Keep the generic user-facing `'API request failed'` response.
-
-**Effort:** 30m. **Tests:** via `caplog`, fail an API fetch with the token in the query string *and* in the path; assert no URL component or token appears in any log record.
-
----
-
-### F4 — User-controlled outbound HTTP header name — **Medium**
-
-**Location:** `routes.py:91-95` — `header_name = request.form.get('api_key_header', 'X-API-Key')` then `headers[header_name] = api_key`.
-
-**Description:** The client supplies the header *name*. A malicious user can set it to `Host`, `Content-Length`, `Transfer-Encoding`, `Connection`, `Authorization`, `Referer`, etc. and `requests` will forward it to the target. `Host` override + the DNS-validated hostname is a (limited) SSRF-adjacent capability; `Transfer-Encoding`/`Content-Length` on the outbound request can produce malformed requests to the target.
-
-**Remediation:** Allowlist header names: only `[A-Za-z0-9-]` plus reject reserved/ hop-by-hop headers (`host`, `content-length`, `transfer-encoding`, `connection`, `proxy-*`, `authorization`, `cookie`, `x-csrf*`). Simplest robust rule: only permit `X-`-prefixed custom headers (matches the UI's default `X-API-Key`), or a fixed allowlist. Validate with a regex and 400 on violation.
-
-**Effort:** 30m. **Tests:** parameterized test in `TestApiFetch`.
-
----
-
-### F5 — Security-header gaps — **Medium**
-
-**Location:** `security.py:45-58` (`apply_security_headers`).
-
-**Description:** Current headers are good but incomplete:
-
-| Missing | Why it matters |
-|---|---|
-| `Strict-Transport-Security` (HSTS) | No HSTS on a TLS-terminated deploy; users are vulnerable to SSL-stripping on first visit |
-| `object-src 'none'`, `base-uri 'self'`, `frame-ancestors 'none'`, `form-action 'self'` in CSP | Shrinks XSS blast radius (object/embed/plugin attacks, `<base>` hijacking, clickjacking via iframes, form exfiltration) |
-| `Permissions-Policy` | Disables unused browser features (geolocation, camera, mic) |
-| `Cross-Origin-Opener-Policy: same-origin` | Mitigates cross-origin window-opener attacks |
-| `Cross-Origin-Resource-Policy: same-origin` | Prevents other origins from embedding/reading our responses |
-
-`upgrade-insecure-requests` is **required**, not optional: F14's completion criterion and the checklist both demand it, so the remediation here states it as mandatory for any deployment served over HTTPS (it is inert on plain-HTTP deployments, which are already out of policy per F14).
-
-**Remediation:**
-
-```python
-response.headers['Strict-Transport-Security'] = 'max-age=31536000; includeSubDomains'  # only when request.is_secure / X-Forwarded-Proto=https
-response.headers['Permissions-Policy'] = 'camera=(), microphone=(), geolocation=()'
-response.headers['Cross-Origin-Opener-Policy'] = 'same-origin'
-response.headers['Cross-Origin-Resource-Policy'] = 'same-origin'
-CSP += "; object-src 'none'; base-uri 'self'; frame-ancestors 'none'; form-action 'self'"  # note the leading '; ' separator
-```
-
-Build the CSP as a list of directives (or keep the trailing `;` in the base string) so appending can never concatenate tokens into a malformed directive. `X-Frame-Options: DENY` stays as legacy fallback. Guard HSTS behind `is_secure` (or a `FORCE_HTTPS` config) so local `http://localhost` dev is unaffected.
-
-**Effort:** 1h. **Tests:** extend `TestSecurityHeaders` to assert each new header; ensure CSP still allows Google Fonts and `data:` images.
-
----
-
-### F6 — SSRF gaps: blocking DNS lookup, no port restriction, residual rebinding — **Medium**
-
-**Location:** `security.py:23-26` (`socket.getaddrinfo(hostname, None)`), `routes.py:119-127`.
-
-**Description:** Three distinct items:
-
-1. **No timeout on `getaddrinfo`.** The call blocks the gunicorn worker for as long as DNS takes. An attacker can submit URLs with slow/unresponsive DNS nameservers and starve workers (rate limit 30/min bounds but does not eliminate this). This is both a security and a performance finding (see `PERFORMANCE_REVIEW` P7).
-2. **Ports are unrestricted.** `http://public.example.com:22` or `:6379` passes validation because only the IP is checked; the tool will happily connect to any port on any public host. Low severity (public hosts only) but worth a documented decision.
-3. **DNS rebinding TOCTOU** is acknowledged in `routes.py:116-118` and `MEMORY.md`; acceptable for an internal tool. Revisit if the app ever becomes a public SaaS.
-
-**What I verified as solid (do not regress):** decimal/hex IP forms (`2130706433`, `0x7f000001`) resolve via `getaddrinfo` to `127.0.0.1` and are rejected; IPv4-mapped IPv6 (`[::ffff:7f00:1]`) has `is_global=False` and is rejected; userinfo tricks (`http://evil@127.0.0.1`) yield hostname `127.0.0.1` and are rejected; `nip.io`-style wildcard domains resolve to real IPs and are checked; `allow_redirects=False` + `raise_for_status()` means 3xx responses never re-connect.
-
-**Remediation (item 1, High-ish priority):**
-- Resolve DNS in a bounded way: run `getaddrinfo` in a **shared, per-process** `ThreadPoolExecutor` (fixed `max_workers`, e.g. 4) with an in-flight semaphore, and wait with `future.result(timeout=API_DNS_TIMEOUT)` (default ~3s). Do **not** create a per-request executor: `Future.result(timeout=...)` only bounds the caller's wait and cannot cancel a running `getaddrinfo`, so per-request executors leak blocked threads and a shared unbounded pool can saturate. A *hard* execution bound requires process isolation or a cancellable resolver — document the timeout as a wait bound and gate concurrency explicitly. Three details are load-bearing, because a timed-out lookup keeps running:
-  - **Permit ownership.** Acquire the semaphore permit *before* `submit()` and release it from the future's **done-callback** (`future.add_done_callback`), never in the caller's `finally` after a timeout. Releasing on caller timeout would re-admit work while the blocked `getaddrinfo` thread is still occupying the pool, which is exactly how the pool saturates under repeated slow-DNS requests. An equivalent formulation is a bounded submission queue whose capacity is the pool size plus a small backlog. When no permit is available within a short admission wait, reject fast (503 / 400 "DNS resolver busy") rather than queueing unboundedly.
-  - **Executor lifecycle across fork.** gunicorn forks workers; an executor created at import time in the master leaves its threads behind in the parent and is not inherited usefully by children. Create it **lazily inside the worker** on first use (module-level singleton behind a lock) or re-create it via `os.register_at_fork(after_in_child=...)`. Do **not** treat `shutdown(wait=False, cancel_futures=True)` as a non-blocking exit guarantee: `cancel_futures` only drops *queued* work, a running `getaddrinfo` cannot be cancelled, and `concurrent.futures` joins its non-daemon threads at interpreter exit whatever `wait` says. **Decided for v1.2: accept and document that there is no bounded teardown.** `security.py:24` calls `socket.getaddrinfo(hostname, None)` with no timeout — the call exposes none — and nothing in the repository defines `API_DNS_TIMEOUT`, an executor, or a resolver bound today. Adding `future.result(timeout=…)` bounds the *caller* only. The teardown wait is therefore whatever the platform resolver takes: glibc defaults to ~5s per nameserver × 2 attempts × every nameserver in `resolv.conf`, so **tens of seconds** is the realistic worst case, and it is bounded at all only when `options timeout:N attempts:M` are explicitly configured. So: do **not** state or imply that v1.2 bounds teardown. Ship the admission control (it bounds *concurrency*, which is the actual worker-starvation fix), document the unbounded recycling wait, optionally pin `options timeout:2 attempts:1` in the container's `resolv.conf` as best-effort, and keep a **killable subprocess** resolver as the escalation that would provide a real bound. The lifecycle tests assert this accepted behavior, not a bound.
-  - **Tests.** (a) Repeated timeouts: patch `getaddrinfo` to sleep well past `API_DNS_TIMEOUT`, issue more requests than `max_workers`, and assert every caller returns within its bound, that permits are not leaked (the in-flight counter returns to zero once the sleeping lookups finish), and that no unbounded thread growth occurs. (b) Saturation: with all permits held, a new request gets the fast admission error rather than blocking. (c) Lifecycle: the executor used by a request is the one created after fork, and teardown behaves as accepted. Do **not** assert a wall-clock bound on recycling: `API_DNS_TIMEOUT` bounds `Future.result()` only, the executor thread stays blocked until the platform resolver returns, and asserting a bound the code does not enforce yields a flaky or falsely reassuring test. Assert the *caller* and *admission* timeouts instead, and have teardown stay blocked until the mocked lookup is explicitly released — that is the documented behavior, so that is what the test should pin.
-- Add `API_ALLOWED_PORTS` (default `80,443,8443`) — cheap and kills most non-HTTP abuse.
-- Keep the residual-rebinding comment; document the port decision in `MEMORY.md`.
-
-**Effort:** 1-2h. **Tests:** mock `getaddrinfo` to raise/sleep and assert the bounded *caller* wait (`Future.result`) and the admission error under saturation — never a bound on teardown, which nothing here enforces; port rejection tests.
-
----
-
-### F7 — Default SECRET_KEY has no production fail-fast — **Medium**
-
-**Location:** `config.py:9`, `app.py:9-25`.
-
-**Description:** `SECRET_KEY = os.environ.get('SECRET_KEY', 'dev-secret-key-change-in-production')`. If an operator forgets to set it (README calls it "Required: Yes"), the app silently runs with a *publicly known* key: CSRF tokens are forgeable and the session cookie can be signed. `render.yaml` sets `generateValue: true`, but self-hosted / Docker deploys from README rely on the operator.
-
-**Remediation:**
-- In `create_app()`, after config load: when the production signal is set and `SECRET_KEY` equals the dev default (or is `None`/empty), `raise RuntimeError('SECRET_KEY must be set in production')`.
-- **`APP_ENV=production` is the single canonical signal.** Do not also accept `PRODUCTION=true` or any alias: two accepted spellings mean a deployment can satisfy one gate and silently miss another. Concretely, if this rule accepted `PRODUCTION=true` while the cookie rule (F16) and the verification checklist read only `APP_ENV`, a deployment setting `PRODUCTION=true` with a valid key would pass the secret-key gate **with `SESSION_COOKIE_SECURE` still off** — a live vulnerability produced purely by the inconsistency. One name, checked by one helper (`is_production()`), used by F7, F16, and the 2.10 topology guard alike. Do **not** infer production from `not DEBUG` — the documented local run `python app.py` has `DEBUG=False` by default, and gating on it would block ordinary development startup.
-- Also validate that config integers are actually integers (env typo like `MAX_UPLOAD_SIZE=abc` currently raises `ValueError` at import time with a confusing traceback; wrap with clear messages).
-
-**Effort:** 30m. **Tests** — cover **every** branch this finding adds, not just the unset-key one: (a) `APP_ENV=production` + `SECRET_KEY` unset (dev default) → `RuntimeError`; (b) `APP_ENV=production` + **`SECRET_KEY=""`** (empty string — a distinct branch from unset, and the one a misconfigured secrets manager actually produces) → `RuntimeError`; (c) `APP_ENV=production` + a valid key → starts; (d) `APP_ENV` unset (local dev) + the default key → starts; (e) the integer-validation branch: `MAX_UPLOAD_SIZE=abc`, and one bad value for **each** integer setting (`PREVIEW_ROW_LIMIT`, `API_FETCH_TIMEOUT`, `API_FETCH_MAX_RESPONSE`, `FLATTEN_MAX_DEPTH`, `API_DNS_TIMEOUT`, `MAX_EXPORT_CELLS`, `APP_WORKERS`, `APP_REPLICAS`) → the documented clear error, not a raw `ValueError` traceback; (f) `PRODUCTION=true` alone is **not** honored as a production signal (guards against the two-spellings hole above). Do not construct `Config(SECRET_KEY=...)` — `Config` is a class with class attributes, not a constructor; drive behavior via environment variables or `app.config` mutation after load.
-
----
-
-### F8 — Recursion-depth DoS in data-processing helpers — **Medium**
-
-**Location:** `helpers.py:34-62` (`extract_table_data` recurses at lines 54-58), `helpers.py:82-111` (`find_candidate_arrays` recurses at line 109).
-
-**Description:** `flatten_for_csv` has a `max_depth` guard, but `extract_table_data` (recurses at lines 54-58) does not; `find_candidate_arrays` (recurses at line 109) is dead code slated for removal in roadmap Phase 0. A 10 MB JSON payload nested ~1000+ levels deep (valid JSON) will hit Python's recursion limit inside `extract_table_data` → `RecursionError` → 500 (or worse, in older interpreters, C-stack issues). The server also has no JSON-parse depth control.
-
-**Remediation:**
-- Add `_depth=0, max_depth=...` guards to `extract_table_data` mirroring `flatten_for_csv`'s pattern (deep remainder → JSON-stringify or bail to a single row). No guards are needed for `find_candidate_arrays` — it is deleted in roadmap Phase 0.
-- Defensively wrap `json.loads`/`parse_jsonl` calls: catch `RecursionError` and return a 400 (`'JSON nesting too deep'`).
-- Note: CPython's `json` C parser can itself raise `RecursionError` on pathological nesting — that is caught by the same wrapper.
-
-**Effort:** 1h. **Tests:** construct a 1500-deep nested structure (iteratively, no recursion in the test) and assert 400 or graceful degradation; `extract_table_data` on depth-capped input.
-
----
-
-### F9 — API JSONL parse failure returns 500 and logs exception details — **Medium**
-
-**Location:** `routes.py:139-151` (API branch) + `routes.py:197-199` (outer handler).
-
-**Description:** In the API branch, `parse_jsonl(text)` raises `ValueError` when a line is malformed, but only `Timeout`, `RequestException`, and `JSONDecodeError` are caught. The `ValueError` therefore propagates to the outer `except Exception` → returns `500 'An internal error occurred'` (wrong status: client error → should be 400) and records an unnecessary exception traceback. Note: `str(JSONDecodeError)` contains only the parser diagnostic and line/column offsets — **not** the document text — so no payload snippet reaches the logs via this path (the `.doc` attribute is not formatted by the traceback).
-
-**Remediation:** In the API branch, add `except ValueError: return jsonify({'error': 'API response is not valid JSONL'}), 400` (before the generic handler) so the client gets a 400 and the exception is neither logged nor returned. For file/paste the `ValueError` path is already handled with 400 (`routes.py:62-63, 74-75`) and is the user's own data — acceptable to keep verbatim.
-
-**Effort:** 30m. **Tests:** mock API returning malformed JSONL → assert 400 with the generic message and, via `caplog`, that the ValueError is not logged (this is the known-uncovered branch from `docs/code-health-final.md` §4.2).
-
----
-
-### F10 — Oversized-request rejection is HTML, not JSON — **Low**
-
-**Location:** `config.py:12` (`MAX_CONTENT_LENGTH`), app-wide.
-
-**Description:** Requests over 10 MB hit Flask's built-in 413 handler which returns an HTML page. Every other error path in this app returns `{"error": ...}` JSON, so client code (`response.json()` in `app.js:127`) will throw a `SyntaxError` on the HTML body and surface a confusing error.
-
-**Remediation:** Register an `app.errorhandler(413)` returning `jsonify({'error': 'Request too large (max 10MB)'}), 413`. Optionally also a generic `500` JSON handler for non-route errors.
-
-**Effort:** 20m. **Tests:** POST a >10 MB body → assert 413 + JSON.
-
----
-
-### F11 — No `Cache-Control: no-store` on data-bearing responses — **Low**
-
-**Location:** `routes.py:188-195` (`/process`), `routes.py:230-238`, `routes.py:283-289`.
-
-**Description:** `/process` and the export endpoints return sensitive payload data. Without `Cache-Control`, shared caches/proxies/browser bfcache may retain it. The index page can be cached; data responses should not.
-
-**Remediation:** In `apply_security_headers` or per-route: `response.headers['Cache-Control'] = 'no-store'` for `/process`, `/export-csv`, `/export-xlsx`, `/health`; keep default/`public` for `/` and static assets (see performance review P6).
-
-**Effort:** 20m. **Tests:** assert header on the four routes.
-
----
-
-### F12 — Rate limiting is ineffective behind a proxy — **High**
-
-**Location:** `extensions.py:7` (`Limiter(key_func=get_remote_address)`), `config.py:21` (`memory://`), deployment (Render/Nginx).
-
-**Description:** `get_remote_address` uses `request.remote_addr`. Behind Render's load balancer / Nginx, every request appears to come from the proxy IP, so **all users share one rate-limit bucket** — an attacker can exhaust the entire site's `/process` quota for everyone (availability), and per-user limits don't exist. Additionally, `memory://` storage is per-gunicorn-worker: with N workers the effective limit is N× the configured one (documented in `MEMORY.md`, but the proxy issue is not).
-
-**Remediation:**
-- Configure `ProxyFix` (Werkzeug) in `create_app()` with `x_for=1, x_proto=1, x_host=1` **only when behind a trusted proxy** (opt-in via env var, e.g. `TRUST_PROXY=1` — do not trust client-supplied `X-Forwarded-For` unconditionally, that's spoofable).
-- Alternatively set a custom `key_func` that uses the rightmost non-trusted hop.
-- Keep `memory://` only for the **single-worker, single-instance** default. Counters are process-local, so the effective limit is multiplied by **`workers × replicas`**: any deployment above 1×1 must set a shared `RATELIMIT_STORAGE_URI` (`redis://...`) or it is not enforcing the configured limit — README's three `--workers 4` examples and roadmap 2.8's `--workers 2` are all affected, as is any Render `numInstances > 1`. Note `config.py:21` **hardcodes** `RATELIMIT_STORAGE_URI = 'memory://'`, so shared storage is not even configurable today; that is the first fix. The worker count must then come from **one enforced source**, not a second declaration that can drift: derive the start command from `WEB_CONCURRENCY` (`--workers "$WEB_CONCURRENCY"`) so the value the app validates is the value gunicorn uses, and enforce `APP_REPLICAS` at the deployment layer mirroring `render.yaml`'s `numInstances`. Defaulting either to `1` fails open — an undeclared 4-worker deployment reads as single-worker — so under `APP_ENV=production` both must be explicitly declared, and shared storage is required whenever either exceeds one **or cannot be verified**. Correct the deployment examples and test the process-local semantics explicitly rather than leaving them implied (roadmap 2.10).
-
-**Effort:** 1h. **Tests:** with `TRUST_PROXY=1`, assert `request.remote_addr` is the client IP from `X-Forwarded-For`.
-
----
-
-### F13 — Upload validation: extension and content-type unchecked — **Low**
-
-**Location:** `routes.py:48-63`.
-
-**Description:** `accept=".json,.jsonl"` is client-side only; the server accepts any filename/extension and any `Content-Type`. Not a vulnerability by itself (content is parsed strictly), but it enables confusion and wastes processing on binary junk.
-
-**Remediation:** Reject uploads whose filename does not end in `.json`/`.jsonl` (or whose declared `Content-Type` is not `application/json` / `application/x-ndjson` / `text/plain`) with a 400.
-
-**Effort:** 30m. **Tests:** upload `evil.txt` → 400.
-
----
-
-### F14 — Credentials flow over plain HTTP when deployed without TLS — **Low (deployment)**
-
-**Location:** README deployment options (own server / Railway / Fly).
-
-**Description:** API keys, bearer tokens, and basic-auth passwords are POSTed from the browser to this app. Any deployment without HTTPS exposes them. Render and the Nginx guide provide TLS; the other quick-start options do not state it.
-
-**Remediation:** Documentation only: make "HTTPS required" explicit in every deployment path; add `upgrade-insecure-requests` to CSP (F5); optionally refuse to run the API-fetch feature over plain HTTP.
-
-**Effort:** 30m (docs).
-
----
-
-### F15 — `/health` discloses version — **Low / Info**
-
-**Location:** `routes.py:29-35`.
-
-**Description:** Version string aids attackers in targeting known CVEs. Common tradeoff for ops tooling.
-
-**Remediation:** Keep the current behavior — `/health` always returns `version` (the existing `tests/test_routes.py` assertion and the `AGENTS.md`/`CLAUDE.md` contract depend on it). Optionally gate disclosure behind `HEALTH_REVEAL_VERSION` with a **default of on** (i.e. no behavior change) so operators may opt out. Not urgent; log the decision in `MEMORY.md`.
-
----
-
-### F16 — Session/cookie hardening — **Low**
-
-**Location:** `config.py` (no `SESSION_COOKIE_*`), `render.yaml`.
-
-**Description:** Flask 3.x cookie defaults are `HttpOnly=True`, `SameSite=None` (no `SameSite` attribute emitted; browsers then apply `Lax`), and `Secure=False`. `Secure` is **not** auto-enabled by `request.is_secure` — it must be set explicitly, and correct detection behind a TLS-terminating proxy requires ProxyFix (F12). Given no server-side sessions are used, the CSRF token is the real secret — still worth locking down.
-
-**Remediation:** Set explicitly: `SESSION_COOKIE_HTTPONLY = True`, `SESSION_COOKIE_SAMESITE = 'Lax'`, and `SESSION_COOKIE_SECURE` tied to the **explicit production signal** (`APP_ENV=production`), not `not DEBUG` — a plain local run has `DEBUG=False` and would otherwise send `Secure` cookies over HTTP, breaking CSRF-protected POSTs. Couple secure-request detection with ProxyFix from F12 where needed. Optionally `WTF_CSRF_SSL_STRICT`.
-
-**Effort:** 20m. **Tests:** config assertions.
-
----
-
-### F17 — Documentation drift — **Info**
-
-**Location:** `MEMORY.md:66-70`, `CLAUDE.md:96`, `AGENTS.md` (project snapshot), `README.md:6,434-436`, `LICENSE` (GPL-3.0 vs README/CLAUDE MIT).
-
-**Description:** Several docs describe the **old** multi-array handshake (`/process` returns `candidates`) but the code (commit `e537042`) returns `raw_json` and the frontend shows a JSON tree picker. Also the repo license is now GPL-3.0 (`LICENSE`, commit `400f15a`) while README/CLAUDE still claim MIT and the README badge references no file. Stale docs mislead future contributors (e.g. an agent could "re-add" the candidates field).
-
-**Remediation:** Update `MEMORY.md` (multi-array handshake entry → tree-picker), `CLAUDE.md` `/process` description, `AGENTS.md` snapshot, README license text/badge; add CHANGELOG. Folded into roadmap Phase 5.
-
----
-
-## 3. Finding-to-Remediation Matrix
-
-| ID | Finding | Severity | Remediation | Effort |
-|---|---|---|---|---|
-| F1 | CSV/XLSX formula injection | Critical | Sanitize `=+-@` leading chars in all 4 export paths | 1-2h |
-| F2 | 7 dependency CVEs (gunicorn smuggling High) | High | Pin upgrades + dev-deps split + re-audit | 1h |
-| F12 | Rate limit shared-bucket behind proxy | High | ProxyFix opt-in + key_func | 1h |
-| F6 | DNS lookup no timeout / ports unrestricted | Medium | Bounded resolver + port allowlist | 1-2h |
-| F3 | Query-param token in error logs | Medium | Fixed log message (no URL) | 30m |
-| F4 | User-controlled outbound header name | Medium | Header-name allowlist/regex | 30m |
-| F5 | Missing hardening headers / HSTS | Medium | Extend `apply_security_headers` | 1h |
-| F7 | Dev SECRET_KEY accepted in prod | Medium | Startup fail-fast + config validation | 30m |
-| F8 | Recursion-depth DoS in helpers | Medium | Depth guards + RecursionError → 400 | 1h |
-| F9 | API JSONL ValueError → 500 (should be 400) | Medium | Catch ValueError in API branch | 30m |
-| F11 | No `Cache-Control: no-store` on data | Low | Headers on data routes | 20m |
-| F10 | 413 returns HTML | Low | JSON error handlers | 20m |
-| F13 | Upload extension/type unchecked | Low | Filename/content-type checks | 30m |
-| F14 | Plain-HTTP credential exposure | Low | Docs + CSP upgrade-insecure-requests | 30m |
-| F15 | `/health` version disclosure | Low | Keep by default; optional gate (default on) | 30m |
-| F16 | Session cookie flags | Low | Explicit cookie config | 20m |
-| F17 | Docs drift (license, handshake) | Info | Doc sync in roadmap Phase 5 | 1h |
-
----
-
-## 4. Verification Checklist (post-fix)
-
-- [ ] **F1** Export CSV, TSV, XLSX with values `=SUM(A1)`, `@cmd`, `+1`, `-1`, tab-, CR-, and LF-prefixed — open the result in a spreadsheet (including after an Excel save/reopen for CSV) and confirm **no formula executes** (values render as text).
-- [ ] **F2** `pip-audit -r requirements.txt` → 0 vulnerabilities; full `pytest` suite green.
-- [ ] **F3** Via `caplog`, a failing API fetch with the token in the query string *and* in the path produces log records containing no URL component or token.
-- [ ] **F4** `api_key_header` set to `Host` / `Content-Length` / `Transfer-Encoding` → 400; the outbound request carries no reserved/hop-by-hop header.
-- [ ] **F6 (IPs)** SSRF: `http://127.0.0.1`, `http://169.254.169.254`, `http://2130706433`, `http://[::ffff:7f00:1]`, `http://0x7f000001` all → 400.
-- [ ] **F6 (DNS)** Slow-DNS hostname (mock) does not block a worker beyond the configured DNS timeout; concurrent lookups respect the in-flight limit.
-- [ ] **F6 (ports)** API fetch to `http://public.example.com:22` / `:6379` → 400 (port allowlist `80,443,8443`).
-- [ ] **F7** A POST without CSRF token → 400; with the dev SECRET_KEY default and `APP_ENV=production`, `create_app()` refuses to start (plain local run without `APP_ENV` still starts).
-- [ ] **F8** 1500-deep JSON → 400 (`'JSON nesting too deep'`), not 500.
-- [ ] **F9** API-fetch of malformed JSONL → 400 with generic message; the ValueError is not logged (`caplog`).
-- [ ] **F10** >10 MB POST → JSON 413 (not HTML).
-- [ ] **F11** Data routes (`/process`, `/export-csv`, `/export-xlsx`, `/health`) send `Cache-Control: no-store`.
-- [ ] **F12** With `TRUST_PROXY=1`, rate-limit buckets are per-client-IP and forged `X-Forwarded-For` headers are ignored.
-- [ ] **F13** Upload `evil.txt` or a non-JSON content-type → 400.
-- [ ] **F14** Deployment docs state HTTPS is required on every path; CSP includes `upgrade-insecure-requests` (manual sign-off).
-- [ ] **F15** `/health` still returns `version` by default; `HEALTH_REVEAL_VERSION=0` hides it (config test).
-- [ ] **F16** Session cookie flags: `HttpOnly`, `SameSite=Lax`, `Secure` under `APP_ENV=production` and **not** on a plain local run (assert `Set-Cookie`).
-- [ ] **F17** Docs scan: no stale `candidates`/MIT references in `MEMORY.md`/`CLAUDE.md`/`AGENTS.md`/`README.md` (manual sign-off).
-- [ ] **F5** Response headers: HSTS (secure requests), `Permissions-Policy`, `COOP`, `CRP`, extended CSP (`object-src 'none'; base-uri 'self'; frame-ancestors 'none'; form-action 'self'`).