Represent the execution of a specific stage within a pipeline run.
stage_runs is the central processing debugging table. It identifies exactly
where a pipeline run failed, succeeded, skipped, or became blocked.
stage_run_idstage_run_id is globally unique inside the processing registry.stage_run_id is immutable after creation.pipeline_run_id links the stage run to its complete pipeline execution.paper_id denormalizes the paper relationship for debugging and querying.stage_runs is owned by victus-processing.
CREATE TABLE stage_runs (
stage_run_id TEXT PRIMARY KEY,
pipeline_run_id TEXT NOT NULL REFERENCES pipeline_runs(pipeline_run_id),
paper_id TEXT NOT NULL REFERENCES papers(paper_id),
stage_name TEXT NOT NULL,
stage_order INTEGER NOT NULL,
status TEXT NOT NULL,
input_artifact_ids TEXT[] NOT NULL DEFAULT '{}',
output_artifact_ids TEXT[] NOT NULL DEFAULT '{}',
error_id TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
started_at TIMESTAMPTZ,
finished_at TIMESTAMPTZ
);
| Field | Type | Description |
|---|---|---|
stage_run_id |
TEXT | Primary identifier for the stage execution. |
pipeline_run_id |
TEXT | Parent pipeline run. |
paper_id |
TEXT | Paper being processed. |
stage_name |
TEXT | Stable stage name. |
stage_order |
INTEGER | Stage order within the pipeline run. |
status |
TEXT | Current stage execution status. |
input_artifact_ids |
TEXT[] | Artifact ids consumed by this stage. |
output_artifact_ids |
TEXT[] | Artifact ids produced by this stage. |
error_id |
TEXT / NULL | Primary processing error for this stage, when present. |
created_at |
TIMESTAMPTZ | Stage run creation timestamp. |
started_at |
TIMESTAMPTZ / NULL | Stage run start timestamp. |
finished_at |
TIMESTAMPTZ / NULL | Stage run finish timestamp. |
stage_runs must:
error_idstage_runs must not store:
stage_run_id, pipeline_run_id, paper_id, stage_name, stage_order,status are required.pipeline_run_id must reference an existingpipeline_runs.pipeline_run_id.paper_id must reference an existing papers.paper_id.status must be one of the allowed states.input_artifact_ids and output_artifact_ids must always be arrays.stage_order must be non-negative.started_at must not be set before created_at.finished_at must not be set before started_at when both are present.metadata_resolutionpdf_ingestionpdf_to_markdownmarkdown_batchingstructured_block_extractionpaper_classificationscientific_block_trimmingexperiment_mappingcanonical_evidence_extractionartifact_packagingpromotionindexingpendingrunningsucceededsucceeded_with_warningsfailedskippedblockedcancelledCreated when the stage is planned or registered for a pipeline run.
Updated as the stage starts, finishes, fails, is skipped, is blocked, or is
cancelled.
Not deleted under normal operation.
Deprecated only through a future contract version or superseded pipeline model.
ProcessingPapersPipelineRunsProcessingArtifactsProcessingErrorsstage_runs.pipeline_run_id -> pipeline_runs.pipeline_run_idstage_runs.paper_id -> papers.paper_idstage_runs.error_id -> processing_errors.error_idartifacts.stage_run_id -> stage_runs.stage_run_idprocessing_errors.stage_run_id -> stage_runs.stage_run_idstage_runs is the first table to inspect when debugging a failed pipeline
execution. Detailed error payloads belong in processing_errors.
Documentation clarification or validation wording refinement.
Backward-compatible additions such as nullable columns, new stage names, or new
non-breaking status values.
Breaking schema changes, identity changes, stage meaning changes, status meaning
changes, or field removals.