feat(templates): formulation.toml emission in the vetted template + free skeleton

[aarontrowbridge]

---

type: issue-draft
repo: harmoniqs/amicode
tier: standard
date: 2026-10-04
spec: spec-20261004-170307-disclosure-system-v1

Important

Problem — The formulation record (formulation.toml — the machine-readable problem statement a run emits so the PI can see and correct what was actually solved, per the formulation-record contract) exists today only when someone hand-writes a one-off extraction probe against a script's construction block. The two records we have were both produced that way. The next campaign run will produce none. Worse, the upstream spec extraction has two measured gaps (filed upstream as piccolo#366): the retained spec drops the bending regularizer weight, the free-Δt bounds, and the drive-derivative bound, and the integrator block is absent from best-effort extraction — so even a wired-up emission would silently produce a record that lies about being complete on the most common path (the vetted template).
Approach — Move the emission into the two template surfaces the extension ships, as a script-side, fire-and-forget idiom: after problem construction and before the solve, the script writes formulation.toml atomically (tmp + mv, same pattern as the result file) — the retained spec for spec-built problems, best-effort extraction with a visible non-canonical flag plus call-site solver actuals otherwise. The idiom is wrapped: an emission failure prints one receipt line and the solve proceeds — a run without a record never blocks, by the frozen parent contract. The four measured gap fields travel in a call-site template_actuals block, honestly labeled, until the upstream fix retires it. Every record carries a schema_version field, and best-effort records cap raw inline matrices to a digest + dimensions at emission time (run dirs sync across machines). The free-tier skeleton's contract block gains the same emission requirement so future authored scripts inherit it.
Scope — in: the vetted solve template (pulse-designer score), the free-tier skeleton, construction-only fixture verification of both · out: harness/gate changes (enforcement stays on the render side, which already renders missing records UNBACKED), composed exemplars (they gain the idiom as they are revised), the upstream Piccolo extraction fixes (tracked as piccolo#366), the report cadence and delivery (separate slices of the same spec).
Assumptions — the parent formulation-record contract is frozen and binds; the renderer's tolerance rule (unknown blocks preserved, never fatal) lands in the companion slice; construction-only fixture runs are bounded and never optimize.

Acceptance Criteria

• A spec-built problem through the new template idiom, in a construction-only run, emits formulation.toml with canonical == true and every row of the fixed record inventory (system, goal, pulse, wrappers, warm_start from the upstream schema; integrator+alg, bending weight, Δt bounds, drive-derivative bound from template_actuals; solver actuals from the call site; schema_version from the idiom itself)
• An emission failure never blocks the solve — a fixture whose write path fails completes the run and prints exactly one receipt line (tested)
• The free-tier skeleton's contract block contains the emission requirement line
• A script authored strictly from the skeleton produces a schema-valid formulation.toml in a construction-only run
• Best-effort records carry canonical = false, cap raw matrices to digest + dims, and the call-site actuals blocks are visibly labeled as actuals
• A run from an old template (no schema_version) is distinguishable from a new-template emission failure in the record's absence pattern

Testing Decisions

Extend the existing report-suite pytest module (the formulation-record renderer tests) with the named emission tests — the fixture and identity checks belong beside the renderer contract they feed; no new suite surface.

Key Decisions

• Emission in the script, not the harness — the parent contract froze "produced by the script at launch"; the gate binary is a compiled sysimage and the render side already owns the UNBACKED teeth, so no gate change.
• template_actuals now, upstream later — the call-site append closes the four measured gaps today; the upstream fix is tracked and retires the append in a follow-up.
• Fire-and-forget is what keeps the frozen invariant true — "a run without a record never blocks" must hold against emission-code failure, not just emission absence; the idiom is wrapped by contract, and a test pins it.
• Matrix cap at emission, not only at render — the parent's trust obligation caps raw matrices in the record itself, so synced run dirs never grow Hamiltonian payloads.

Constraints & Invariants

• Best-effort semantics inherit the house doctrine: nothing here ever blocks a solve.
• Corrections target the spec or the script, never a rendered artifact (parent D4).
• No real campaign data in fixtures — synthetic only; the repo is public.
• The emitted record is never edited after emission (parent invariant); the actuals blocks are appended by the run before the record is sealed.

Prior Art

• The formulation-record contract (the parent spec, linked) and its fill-contract companion in the report template directory — the render-side UNBACKED handling that makes best-effort emission safe.
• The two hand-extracted records from the October sessions (OQC and the promoted neutral-atom gate) — the probe-script path this replaces, and the field set the fixtures must reproduce.
• The upstream spec system (extract_spec + object verification) — the verified round-trip the spec-built path rides on; its gaps are the measured evidence behind template_actuals.

Source

Companion slice to #1700 (the PI report) and #1705 (formulation display) · Parent contract: the formulation-record spec in the personal vault · Upstream gaps: piccolo#366 · Plan of record: the disclosure-system v1 spec's compiled plan (steps 2–3).

Notes

Drafted through the deliberate loop (spec → three-lens adversarial review → compiled plan); the acceptance list above mirrors the spec's fixed record inventory table verbatim. The renderer-side tolerance and structure-identity tests are step 3 of the same plan — this issue owns the emission side only.

[aarontrowbridge]

Path correction from the upstream read (pre-implementation). The original acceptance criterion pinned the fixture to a "spec-built" problem with canonical == true through the template idiom — that was wrong about the template's own production path. Per extract_spec's upstream contract, a problem built through kwargs (SplinePulseProblem(qtraj, N; ...), exactly how the vetted template builds) has no retained spec: it is hand-built by definition and extracts via the best-effort, explicitly non-canonical path (system.kind = "raw", solver defaulted). The canonical (retained_spec !== nothing) path only arises for problems materialized from a spec.

So the emission idiom handles both branches honestly — canonical is derived (Piccolo.Control.retained_spec(qcp) !== nothing), never asserted — and the tests cover both paths with two fixtures:

1. The template's real path: a construction-only run of the template prefix (sliced from the actual template source, zero fixture drift) → canonical = false, best-effort record + template_actuals (the kwargs the retained params drop: integrator_type = :pwc, the grid-computed R) + solver_actuals from the call site.
2. The canonical branch: a problem materialized from a spec TOML, through the same sliced emission block → canonical = true.

Everything else in the acceptance list stands. Inventory note: the R_bend/Δt_bounds/du_bound gap fields from the original issue text were measured on the OQC/pasqal scripts (cubic-spline + free-Δt family); this template's measured gap set is integrator_type and the grid-R rule — the template_actuals content is per-template, and this issue's template carries its own actual set.