WS4: patchSmith — downloadable Vital (.vital) presets with cited parameters

[slittycode]

What this is

The first half of WS4 (patchSmith): turn measured synthesis character into a downloadable Vital preset where every parameter cites the Phase 1 measurement that justifies it (PURPOSE.md invariant #2), and weak/absent evidence is disclosed, not guessed (invariant #4).

The mapping (apps/ui/src/services/patchSmith.ts, pure & deterministic)

buildPatch(phase1) emits Vital controls, each with a full citation {label, vitalParam, value, display, phase1Fields, rationale, confidence}:

Measurement	→ Vital control	Confidence
supersawDetail.voiceCount / avgDetuneCents	osc_1_unison_voices + osc_1_unison_detune	from detector score
spectralBalance.subBass (strong)	octave-down osc_2 sub layer	MED
acidDetail.* + spectral brightness	resonant filter_1 + cutoff	from detector score
bassDetail.averageDecayMs / type	amp envelope decay / sustain	MED

No measurement → no bound parameter. Low-confidence or absent sources are skipped or set to a conservative default with an explicit hedge; the manifest's overall confidence is the worst band across cited params. synthesisCharacter / textureCharacter inform the preset comments (they have no clean control binding without wavetable editing — a documented v2 follow-up).

Format correctness

The .vital file is JSON. I confirmed against Vital's own load_save.cpp (jsonToState) that missing wavetables/modulations/lfos/sample arrays load on init defaults with no error — so this writes an override-only settings object rather than embedding fragile base64 wavetables. Unit mappers encode Vital's real ValueDetails: env times use seconds = value⁴; filter cutoff is the semitone 69 + 12·log₂(f/440).

Verification

• 14 unit tests: deterministic mapping, citation provenance (every cited param carries ≥1 phase1Fields), hedging on low-confidence/empty inputs, the unit mappers, and a .vital re-parse asserting the JSON shape + in-range control values (the machine-verifiable gate the plan called for).
• npm run lint + build clean; full unit suite 730 passing.

Caveat (honest)

The re-parse test proves the file is structurally valid JSON with in-range controls; it does not prove Vital loads it (I can't run Vital in this container). The format was authored from Vital's source, and the override-only approach is the low-risk path — but a quick load-check in Vital is worth doing before relying on it. This is the lighter analog of the .adg PR's owner-round-trip gate.

Notes

• Independent of fix(loudness): Phase 1 v2 — truePeak→dBTP, bpmConfidence→0–1, coherent PLR #128 / WS3a: asa-dsp ↔ Essentia loudness parity harness (checkpoint) #129; forked from main. Pure frontend; no backend or Phase 1 contract changes.
• The new panel adds a collapsed "Generate Vital patch" button to the results surface → expect a Chromatic snapshot update to accept.

https://claude.ai/code/session_01Wq1vE1D7o3W9xZKSHXz43Q

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE

Summary

Implements patchSmith.ts — the BACKLOG.md item for Phase 3 synth-patch generation. Pure read of Phase 1 synthesis measurements, no backend or schema changes. All 747 unit tests pass (14 new), TypeScript clean. The honest-uncertainty design (hedged manifest alongside the preset, worst-band confidence rollup) is the right call for a tool that can't guarantee Vital round-trip accuracy without actually running Vital.

Findings

Worth considering (not blocking)

mapSubLayer (patchSmith.ts:224–228) writes osc_2_transpose = -12.0 and osc_2_level = 0.5 directly to acc.settings without going through applyCitation. These appear in the downloaded preset but have no entry in the manifest's citations array. The decision to enable osc_2 is cited (osc_2_on → spectralBalance.subBass), and the specific values are just what "octave-down sub layer" means rather than measurement-derived quantities, so it's not a hard invariant #2 violation. But a manifest consumer will see osc_2_on: 1.0 cited and won't see osc_2_transpose: -12.0 or osc_2_level: 0.5 at all. Could add them as citations with confidence: "MED" and the same phase1Fields: ["spectralBalance.subBass"] for completeness.

Informational

detuneCentsToVital's linear cents / 7.0 approximation of Vital's kQuadratic control is acknowledged in the comment. At 35 cents the result is 5.0 (mid-range), but Vital's actual quadratic mapping at 5.0 may not land at 35 cents of spread — expect ear-tuning on first real load.

After "Generate" is pressed there are two download buttons: one in the action prop (header) and one at the bottom of the expanded view. Redundant but not harmful.

Test results

747 passed, 4 skipped. 14 new tests cover unit mappers, citation provenance (invariant #2 check for every cited param), hedge/confidence behavior across all four mappers, determinism, and the .vital re-parse gate. All tests exercise real invariants.

Phase boundary check

Clean. patchSmith.ts and PatchSmithPanel.tsx are read-only consumers of Phase1Result. No mutations, no re-derivations of Phase 1 values, no Phase 1 schema changes.

---

Generated by Claude Code