refactor(#276): Phase 4 — parameter, export, document, saved-query, schema-graph, preferences services

[BorisTyshkevich]

What & why

Part of #276 — the rest of Phase 4 in one PR (user decision at the 4A gate), structured as four extraction commits + a review commit so each piece is independently readable and revertable. Merged so far: #278 (0–1), #279 (2), #281 (3a), #282 (3b), #289 (4A). Design rulings for every extraction are pinned in the issue's Phase-4 comment and were plan-stressed before implementation.

Commit 1 — WorkbenchParameterSession (app.params, 31-test spec): the {name:Type} prepare/gate/exec-view/hardening/recents policy. Thinner cut per plan review: the var strip stays a DOM view calling session methods (no speculative view-model API). Live-state accessors (never snapshots — the filter bar/dashboard/detached view write varValues directly); app.hardenedVars aliases the session's own Set. Both consumers re-pointed at once: the workbench session's param hooks (zero edits to that file) and export's direct calls.

Commit 2 — ExportService + ExportSink (app.exports, 40-test spec): pure move of the re-pointed bodies. Transport deps are ch-client + the live ctx accessor, not app.exec (raw-Response hold-back inspection is incompatible with parsed results). Consolidates the last two duplicated cancellation-state copies from the Phase-0 map. exporting stays an AppState signal with the service as sole writer. The picker-before-auth ordering (transient user activation) is now pinned by an explicit test. The two ~350-line app.test.ts export describes migrated to the in-memory-sink spec; 8 thin integration tests remain.

Commit 3 — QueryDocumentSession + SavedQueryService (app.queryDoc/app.saved, 20+22-test specs): Spec evaluation/document lifecycle (diagnostics typed with the core SpecValidationDiagnostic — no editor imports, check:arch-enforced) and create/commit/history/share persistence returning discriminated-union results. The shell keeps the exact toast messages and the post-commit repaint cascade (a hand-repeated convention at ≥5 call sites — deliberately not service-owned). Prerequisite type-narrowing of six state.ts signatures to exact Picks (type-only). No service-to-service dependency: the shell sequences evaluate → commit.

Commit 4 — SchemaGraphSession + AppPreferences (app.graph/app.prefs, 25+13-test specs; built in a parallel worktree, hand-merged, merge verified against both parents by a dedicated review finder): the lineage lifecycle moved on the WorkbenchSession template (session mutates tab.result in place + injected repaint hook; explicitly-captured tab reference; reference-identity stale guard verbatim; expand() returns data — the shell keeps the open-window-before-await popup-blocker invariant); AppState.schemaGraphAbortController deleted (session-private, zero external refs). AppPreferences is the deliberately narrow typed persistence surface.

Commit 5 — review fixes (three-finder full-diff pass): restored a lost end-to-end pin (exportEntry unavailable in Spec mode — the unit gate can't catch that wiring), trimmed AppPreferences' eight zero-caller setters (speculative surface), added the missing fake-app Partial-override plumbing for graph/prefs/exports, removed five dead app.ts imports.

Invariants pinned throughout: sessionParams/needsSession/sessionParamsFor stay app.ts-local (their home is a Phase-5 decision — resolved a genuine 4B/4C ownership collision); recordHistory's conditional History repaint stays shell; activateInvalidSpecDraft stays shell (>80% DOM). Known pre-existing wart preserved verbatim: exportDirect names files with ambient Date.now() rather than the injected wallNow().

Verification: full gate green (113 files / 3,214 tests + tsc + check:arch), build green, e2e chromium+webkit 80/80 (the accepted signal on this shared box per #289). app.test.ts changed only in the export describes; every other suite passes unmodified. app.ts: 2,964 → 1,761 lines.

Acceptance criteria completed (cumulative): export in ExportService with injectable sink ✅; parameter policy outside the var-strip renderer ✅; QueryDocumentSession represents open-document behavior ✅; saved-query/history/share behind a focused service ✅; schema-graph lifecycle outside app.ts ✅; a unit test can execute a query, run a dashboard tile, validate parameters, and export to an in-memory sink without DOM ✅.

Remaining for #276: Phase 5 (wire session destroy()s + catalog.invalidate() into real lifecycle, delete the App delegates, split renderApp into route shells, rewrite docs/ARCHITECTURE.md).

Checklist

• npm test passes (the per-file coverage gate is non-negotiable)
• Tests added/updated in the same change as the code
• npm run build succeeds (single-file dist/sql.html)
• Layers kept honest: pure logic in src/core/, network in src/net/ (injected fetch), DOM in src/ui/
• No new runtime dependency (or it's a deliberate, justified addition — see CONTRIBUTING)
• README / CHANGELOG.md ([Unreleased]) updated if behavior or the deployed surface changed
• Reconciled affected tracked work (roadmap Roadmap to 1.0.0 #68, the issue body, ADR/CHANGELOG) if this change reshaped it

🤖 Generated with Claude Code