Artifact Contract¶

Astraeus persists inputs, provenance, outcomes, and detailed results beneath a namespaced runs/ root. The filesystem bundle is the durable authority; the Console, Monitor, reviews, reports, and AI skills all consume these saved artifacts.

Default Roots¶

Workflow	Default root or result
Core run	`runs/core/<run_id>/`
Sweep	`runs/sweeps/<sweep_id>/`
Batch	`runs/batches/<batch_id>/`
Campaign	`runs/campaign/<campaign-id>/campaign_plan_result.json`

CLI options can choose another root or result path. Paths recorded inside a grouped bundle remain relative to that bundle so it can be moved as one unit.

When the CLI omits a core run id, Astraeus resolves it from runtime.run_id and otherwise derives a deterministic rs-<hash> identifier. Campaign output uses campaign.campaign_id, falling back to the request file stem when needed.

Core Run Contract¶

A normal core bundle uses four primary contract files:

File	Schema or role
`runspec.json`	Canonical expanded RunSpec associated with the execution
`run_manifest.json`	`run_manifest_v2`: product/execution provenance, warnings, artifact inventory, and hashes
`metrics_summary.json`	`metrics_summary_v3`: engineering KPIs and execution quality
`environment_summary.json`	`environment_summary_v2`: operational and configuration context

The execution-normalized input is also written as:

runspec/runspec_execution.json

A typical bundle is:

runs/core/<run_id>/
|-- run_manifest.json
|-- metrics_summary.json
|-- environment_summary.json
|-- runspec.json
|-- runspec/
|   |-- runspec.source.yaml
|   `-- runspec_execution.json
|-- config/
|-- states/
|-- geometry/
|-- coverage/
|-- mission/
|-- transport/
|-- activity/
|-- attitude/
|-- power/
|-- propulsion/
`-- diagnostics/

Only the families produced by the resolved stage plan and selected artifact detail appear.

Provenance And Status¶

run_manifest.json records:

run id, creation time, Astraeus version, runtime version, and revision
input RunSpec hash and shared run_context
requested/resolved stages and execution status
artifact families and individual artifact hashes
validation and execution warnings

metrics_summary.json is the first engineering-outcome read. It separates external stages from internal modules and records KPI, quality, warning, and source-artifact context. environment_summary.json records the operating and configuration profile used for the same run.

When component profiles are used, config/component_profile_resolution.json records which profile supplied each expanded block. Execution uses the concrete canonical runspec.json, not the unexpanded reference.

Artifact Families¶

Family	Typical evidence
`states/`	Satellite inventory, timestamps, state vectors, and timeline metadata
`geometry/`	Ground and inter-satellite samples or access windows
`coverage/`	Point, region, fold, revisit, and aggregation results
`mission/`	Service or observation definitions, events, products, and KPIs
`transport/`	Delivery, backlog, latency, link, gateway, beam, scheduler, ISL, and route evidence
`activity/`	Spacecraft-facing operating and activity timelines
`attitude/`	Commanded and realized pointing, modes, transitions, and availability
`power/`	Generation, load, battery, margin, coupling, and sizing results
`propulsion/`	Burns, state change, mass, and propellant accounting
`diagnostics/`	Optional execution and resource diagnostics

Model pages define the units and interpretation of their detailed tables. An absent family normally means the stage did not run or the artifact detail did not request that output.

State Timeline¶

The canonical propagated-state timeline is:

states/timeline_state_vectors_teme.parquet

Required columns are:

Column	Meaning
`timestamp_utc`	Sample time in UTC
`satellite_id`	Resolved satellite identifier
`x_km`, `y_km`, `z_km`	TEME position components in kilometres
`vx_km_s`, `vy_km_s`, `vz_km_s`	TEME velocity components in kilometres per second

Supporting files normally include timeline_summary.json, satellites.json, and timestamps.json; CSV state output may be present when requested. timeline_summary.json records the frame, backend metadata, step, satellite count, timestamp count, and array shapes.

The Console requires a current run contract and suitable state or model artifacts for each pane. The state timeline enables orbit views; each optional analysis pane additionally requires its own model artifacts.

Other families may contain their own event or sample timelines. Their cadence and semantics belong to the owning model, while the propagated state timeline remains authoritative for spacecraft state.

Sweep Bundle¶

runs/sweeps/<sweep_id>/
|-- base_runspec.json
|-- sweep_plan.json
|-- sweep_attempts.json
|-- sweep_results.json
|-- sweep_summary.json
|-- sweep_summary.csv
`-- cases/<case_id>/attempts/<attempt_id>/

File	Role
`sweep_plan.json`	Deterministic expansion and child RunSpec references
`sweep_attempts.json`	Append-only attempt history and per-attempt outcomes
`sweep_results.json`	Current/latest state for every planned case
`sweep_summary.json`	Requested one-row-per-case comparison contract
`sweep_summary.csv`	Optional convenience export of the same row model

Each attempt directory is a standard core run bundle. sweep_results.json is the selected current view; use sweep_attempts.json when execution history matters.

Batch Bundle¶

runs/batches/<batch_id>/
|-- batch_plan.json
|-- batch_attempts.json
|-- batch_results.json
|-- batch_summary.json
|-- batch_summary.csv
`-- cases/<case_id>/attempts/<attempt_id>/

The batch artifacts have the same responsibilities as the sweep artifacts. The difference is provenance: a batch plan references explicit independent RunSpecs rather than expanding overrides from one base input. Heterogeneous missing summary values are represented as null.

Grouped Path And Recovery Rules¶

Bundle references use forward-slash relative paths and must not escape the bundle root.
Planning preserves the source input and materialized canonical child specs.
Resume and rerun add attempts instead of overwriting earlier evidence.
Results select the current/latest attempt; attempts retain execution history.
JSON is the summary contract. CSV is an optional convenience view and does not carry richer semantics.

Campaign Artifacts¶

Campaign planning uses a separate self-contained result contract rather than a core run directory. See Campaign Result Contract for its status, embedded request, summaries, and optional mission side bundles.

Compatibility And Integrity¶

Review the schema version before loading or comparing an artifact.
Use the product version and input hash in the manifest when reproducing a result.
Treat a hash mismatch, missing required file, or unsupported schema as an integrity or compatibility problem; do not silently repair the bundle.
Derived reviews and reports may live beside a bundle; canonical JSON and Parquet artifacts remain the authoritative evidence.

The protected artifact surfaces, version window, scientific-change rules, and migration behavior are defined under Compatibility And Upgrades.