Define the canonical execution record for one Victus processing run.
PipelineRun identifies, tracks, audits, resumes, and supports reasoning about
one execution of the processing pipeline. It represents execution state, not
scientific content.
run_idrun_id is globally unique inside Victus.run_id is immutable after creation.run_id must be generated before any process event is emitted.run_id.PipelineRun is owned by victus-processing.
{
"run_id": "string",
"pipeline_name": "string",
"pipeline_version": "string",
"execution_mode": "single_paper|batch|stage_only|testing|backfill|replay",
"status": "pending|running|succeeded|failed|partially_succeeded|cancelled",
"input_scope": {},
"started_at": "datetime",
"ended_at": "datetime|null",
"created_by": "string|null",
"summary": {},
"created_at": "datetime",
"updated_at": "datetime"
}
| Field | Type | Description |
|---|---|---|
run_id |
String | Unique identifier for this execution. |
pipeline_name |
String | Name of the pipeline being executed. |
pipeline_version |
String | Version or git reference of the pipeline code or contract set used for this run. |
execution_mode |
Enum | Execution scope. |
status |
Enum | Current run status. |
input_scope |
Object | Structured description of what the run was asked to process. |
started_at |
Datetime | Run start timestamp. |
ended_at |
Datetime / Null | Run end timestamp. |
created_by |
String / Null | Actor or process that created the run. |
summary |
Object | Materialized operational counters produced by the run. |
created_at |
Datetime | Run creation timestamp. |
updated_at |
Datetime | Last run update timestamp. |
PipelineRun must record:
PipelineRun must not store:
run_id must be unique and immutable.execution_mode must be one of the allowed values.status must be one of the allowed values.input_scope and summary must be objects.succeeded if required terminal artifacts arePipelineEvent.single_paperbatchstage_onlytestingbackfillreplaypendingrunningsucceededfailedpartially_succeededcancelledCreated before execution starts and before any event is emitted.
Updated as execution starts, progresses, ends, fails, partially succeeds, or is
cancelled.
Not deleted under normal operation.
Deprecated only by future contract version or run model migration.
None.
PipelineEventArtifactManifestPipelineEvent.run_id -> PipelineRun.run_idArtifactManifest.run_id -> PipelineRun.run_idDurable JSONL target:
data/lake/pipeline_runs.jsonl
PostgreSQL stores paper-scoped stage attempts in paper_pipeline_state; it does
not duplicate complete PipelineRun records.
Documentation clarification or validation wording refinement.
Backward-compatible additions such as nullable fields, additional summary
counters, or additional execution modes.
Breaking schema changes, identity changes, status meaning changes, field
removals, or semantic meaning changes.