Human-Reviewable Simulation Report Export

Cross-project contract for turning one simulation or optimization result into one reviewable composite PNG with a sanitized evidence register.

Node role: Procedure.

Reader task: Turn one declared simulation or optimization result into one portable report that a Human can review without opening the source notebook or run folder.

V1 Contract

Citation class — engineering choice. The route below is a scoped report-presentation contract, not a scientific derivation or a universal solver report format. The owning Workbench resource defines its implementation; other producers retain their own result semantics. Reading or publishing this explanation does not establish runtime availability.

The V1 route is

\[ \boxed{ \text{producer evidence} \rightarrow \text{validated report handoff} \rightarrow \text{one composite PNG} + \text{one sanitized register}. } \]

LaTeX source

\boxed{
\text{producer evidence}
\rightarrow
\text{validated report handoff}
\rightarrow
\text{one composite PNG}
+
\text{one sanitized register}.
}

The report represents one named run or candidate. Its default reading order is:

project-specific result media;
optimization history;
metrics and gates;
optimized parameters;
fixed specifications; and
provenance.

The producer supplies the scientific content and already-formatted values. The report renderer arranges and labels that content; it does not infer physics, derive units, choose success gates, or reinterpret missing values.

Required Handoff

The Workbench technical manifest is the serialized public interface. It must carry enough information to establish:

Group	Required meaning
Report identity	Stable report id, title, source project, associated project-owned Design Target, run or candidate identity, and requested visibility.
Project media	One or more producer-rendered images, their intended order, captions, source identity, and content hash.
Optimization history	Evaluation index, running-best objective value, objective name or contract, termination state, and whether rejected candidates are included.
Tables	Ordered rows for metrics, parameters, fixed specifications, and provenance, with display labels, formatted values, units where applicable, targets or gates where applicable, and status.
Sources	Logical or repository-relative locator, content hash, visibility, producer, and source revision for every consumed artifact.
Output	Destination identity for the composite PNG and sanitized register.

Each table role has one purpose:

Metrics compares extracted or calculated quantities with their targets and gates.
Parameters records the optimized or selected coordinates that reproduce the result.
Fixed specifications records non-optimized geometry, material, model, and solver inputs needed to interpret that result.
Provenance records source revisions, artifact identities, conventions, and replay context.

When a declared value is unavailable, the producer must supply NOT_AVAILABLE and a reason. The renderer must not replace it with zero, an empty cell, a guessed value, or a successful status.

Technical ownership

The Superrepo owns this human-facing content contract, Design Target association, and publication selection. The Circuit Workbench owns the technical manifest and rendering contract, its validation, composition runtime, and producer adapters.

Ownership

Owner	Owns	Does not own
Superrepo	Human-facing report semantics, Design Target association, publication selection, and selected review artifacts under `docs/assets/`.	Renderer implementation, raw solver output, or project-specific physics.
Circuit Workbench	Technical manifest, validation, PNG composition, sanitized-register emission, and shared rendering conventions.	Meaning of a project metric or permission to publish private evidence.
Producer project	Project-specific media, formatted table rows, units, gates, source identities, and a thin adapter into the shared manifest.	Cross-project rendering policy.
Run folder	Raw traces, solver artifacts, complete histories, and replay inputs.	Durable documentation or publication authority.

The Superrepo may retain the selected PNG and its sanitized register. It must not copy the raw run folder merely to publish the report.

Failure Contract

Report generation fails without publishing either output when:

a declared source is absent, unreadable, or has a hash mismatch;
a required report group or row meaning is missing;
NOT_AVAILABLE has no reason;
the requested visibility is broader than any input permits;
a source or register entry would expose an absolute private path;
either destination already exists;
media cannot be decoded or the composition cannot be completed; or
the PNG and register cannot both be committed from the same validated input.

The renderer writes both outputs in a temporary destination and publishes them atomically only after validation and rendering succeed. It never overwrites an existing report and never emits an empty panel, partial register, or placeholder-success image.

Visibility cannot be promoted by sanitization:

\[ \boxed{ \text{report visibility} \preceq \min_i\left(\text{source visibility}_i\right). } \]

LaTeX source

\boxed{
\text{report visibility}
\preceq
\min_i\left(\text{source visibility}_i\right).
}

Published register entries use logical artifact ids or repository-relative locators. Absolute workstation paths are forbidden.

Review and Replay

A Human reviewer must be able to answer:

Which Design Target, run, candidate, and source revision produced this report?
Which panel shows the scientific result, and which panel shows optimizer behavior?
Which metrics passed, failed, or were unavailable?
Which parameters were optimized, and which specifications remained fixed?
Can every displayed value and image be traced to a hash-qualified source without exposing private local paths?

The report is a review surface, not new scientific authority. Quantity and gate meaning remain with the selected model, project-owned Design Target and result resources. Generic Network Trace Views and Extraction Authority helps distinguish what a displayed trace actually measures.

V1 Limits

V1 produces one static composite PNG and one sanitized register for one result. It does not provide an interactive dashboard, PDF layout engine, arbitrary page-layout language, report comparison database, physics-specific plotting library, solver execution, or automatic Design Target promotion.

Review Links

Field	Value
Status	Seed
Review state	Candidate cross-project report-export contract; CONVERGING.
Used by	Hybridized-Circuit Subsystem Reduction and Design and project Design Targets.
Test authorization	`no_test_writes` until Human acceptance.
Open review question	Does this contract preserve enough scientific context and provenance for one portable report without moving project physics or raw artifacts into the Superrepo?