0.1d — Round-trip validate Julia-emitted result.toml and manifest.toml against the shared schemas

[jack-champagne]

Important

Problem

β's bundled solve env emits result.toml + manifest.toml with a hardcoded schema_version and no check that the artifacts actually conform to the schemas the TS side will consume — a silent cross-language drift hazard (a renamed field or a missing required key surfaces only in the field, mid-demo). 0.1a defines the schemas; nothing yet proves the Julia producer honors them.

Approach

Add a Julia-side round-trip validation step that loads the emitted result.toml + manifest.toml and validates each against its shared schema (the same definitions 0.1a publishes), failing the run/CI fast tier with a field-precise error on nonconformance — closing the producer/consumer loop so Julia output and the schemas cannot diverge unnoticed.

Approaches Considered

• Julia validates its own emitted artifacts against the shared schemas (chosen) — single source of truth, drift caught at emit time and in CI.
• TS/CLI validates Julia output after the fact — catches drift later, off the producer, and only when the consumer happens to run.
• Hand-mirror the schema as Julia structs — guarantees drift (two definitions of the contract).

Scope

In: a Julia validator that reads result.toml + manifest.toml and checks them against the 0.1a schema definitions; field-precise failure naming the offending key + path; a CI fast-tier round-trip over golden + freshly-emitted artifacts.
Out:

• SolveSpec / lab.toml / catalog-entry validation — covered by other 0.1 slices; this slice is the two emitted-artifact schemas only.
• HDF5 export / pulse-shape validation — Phase 3; β/0' validate only the TOML run-dir shape, not the pulse blob.
• Schema authoring — owned by 0.1a; this slice consumes those definitions, does not define them.
• Mutating the emitter to add fields — only validation here; contract changes flow from 0.1a.

Assumptions

• The shared schemas are reachable from the bundled Julia env (vendored/copied alongside the solve env, not re-authored in Julia).
• A JSON-Schema validation path is available in Julia (library or thin in-house checker) sufficient for the field-precise error requirement.

---

Acceptance Criteria

• A conforming emitted result.toml and manifest.toml validate clean against the 0.1a schemas via the Julia round-trip. (S16)
• A manifest.toml missing a required key (e.g. schema_version or the resolved-spec/lab id) fails with an error naming the offending key and its path — not a bare pass/fail. (S16)
• A result.toml with a wrong-typed or out-of-range field (e.g. non-numeric fidelity) fails field-precise. (S16)
• An emitted schema_version outside the validator's supported range (unknown/unsupported) fails field-precise, while an artifact stamped with a known prior version still validates clean — i.e. version handling follows the tolerate-known-prior-versions policy, not a hard equality check. (S16)
• The round-trip runs in the CI fast tier and reds the build on any nonconformance of committed golden artifacts or freshly-emitted ones. (S16)
• Mutating a required key in the single shared schema source flips both the TS/CLI validator AND the Julia round-trip from pass to fail on a previously-conforming artifact — proving neither side holds a private copy of the contract. (S16)

Key Decisions

• The producer validates its own output (D1: the Julia solver has a versioned I/O contract; this slice enforces it from the Julia side).
• Validation reuses the 0.1a shared schemas; Julia holds no second copy of the contract.
• This is the S16 Julia round-trip half; the S17 lab.toml validated-on-load field-precise story lives in the 0.1 lab-validation slice. The field-precise quality for these emitted artifacts traces to S16 plus the PRD Testing-Decisions "points at the offending field" promise, not S17.
• schema_version follows the migration policy (Q87): validators tolerate known prior versions within a supported range; only unknown/unsupported versions fail.

Constraints & Invariants

• Single source of truth: exactly one schema definition per artifact, consumed by CLI, extension, CI, and this Julia round-trip.
• Field-precise errors are the contract (the lab-partner promise carried over to emitted artifacts via the Testing-Decisions "offending field" rule), not merely valid===false.
• Validates the TOML run-dir shape only; oblivious to the pulse blob format.

Prior Art / Patterns

• SchemaPackage — the shared-definition source this slice consumes (sibling slice 0.1a).
• Run-directory contract — manifest.toml (required, first; carries schema_version + resolved SolveSpec + lab id) and atomic result.toml are the two artifacts validated here.
• amico-run thin orchestrator (β.1) — emits manifest.toml + FINISHED; the bundled solve env emits result.toml. This slice validates what they produce.
• Contract-shape vs physics split — round-trip is a contract-shape check (fast tier), distinct from the seeded physics smoke (slow tier).

Source

Phase 0' (Contracts/foundation), plan task 0.1 SchemaPackage — the Julia round-trip sub-slice (0.1d), depends on 0.1a. Realizes S16 (Julia round-trip half) and S14 (versioned, machine-checkable artifacts); field-precise error quality traces to S16 + PRD Testing-Decisions ("points at the offending field"). Decisions D1 (versioned solver I/O contract); version handling per Q87 / risk-table "validators tolerate known prior versions". Supersedes β: β shipped no schema layer and emitted result.toml/manifest.toml with a hardcoded schema_version and no conformance check — this slice closes that cross-language drift gap. Related: 0.1a (schema definitions, blocks this), β.1 (manifest/FINISHED emitter), β.3 (template that emits the artifacts). Phasing guard: validates TOML run-dir shape only — no HDF5/pulse validation (Phase 3), no catalog store/consumer (Phase 3).

Testing

Extend the CI fast tier with the schema round-trip: assert clean validation of conforming golden artifacts and field-precise failures on a negative matrix of malformed result.toml/manifest.toml, including a versioned-fixture pair (known-prior tolerated, unknown rejected); pair with the bundled solve env's emit path so freshly-produced artifacts are validated, not only fixtures. (Suite/tier only — test structure decided at the TDD RED step.)

Notes

Slicing check: this is correctly a standalone vertical slice — it depends on 0.1a's definitions but exercises a distinct surface (the Julia producer) and closes a distinct risk (cross-language drift) from the TS-side validators; do not merge into 0.1a, do not split further.

[jack-champagne]

Depends on #15.