This contract governs local filesystem layout for victus-processing.
The layout follows the fundamental processing contract and separates canonical
datasets, physical artifacts, run state, debug payloads, registries, and testing
runs.
Covered:
data/ directories;Not covered:
data/
inputs/
seeds/
seed_dois.jsonl
explored_seed_dois.jsonl
generated_seed_dois/
candidates_seed_dois.jsonl
lake/
paper_metadata.jsonl
paper_candidates.jsonl
paper_pdf_links.jsonl
structured_blocks.jsonl
paper_classifications.jsonl
experiment_maps.jsonl
experiment_packets.jsonl
canonical_evidence.jsonl
pipeline_runs.jsonl # run records
pipeline_events.jsonl # append-only event records
paper_stage_state.jsonl # local current stage state
artifacts/
intake/
pdfs/
pdfs/
{paper_id}.pdf
markdown/
{paper_id}.md
victus-data/
papers/{paper_id}/original.pdf
markdown/{paper_id}/paper.md
structured-blocks/{paper_id}/blocks.json
paper-classification/{paper_id}/classification.json
experiment-maps/{paper_id}/experiment_map.json
evidence-packets/{paper_id}/evidence_packets.json
canonical-evidence/{paper_id}/canonical_evidence.json
victus-ops/
runs/{run_id}/run.json
events/{run_id}/events.jsonl
manifests/{run_id}/manifest.json
errors/{run_id}/errors.jsonl
debug/{run_id}/{paper_id}/...
runtime/
runs/
{run_id}/
manifest.json
errors.jsonl
outbox/
postgres_pipeline_records.jsonl
debug/
runs/
{run_id}/
{paper_id}/
raw_batches.jsonl
failed_batches.jsonl
classifier_input.json
registry/
artifact_manifest.jsonl
artifact_registry.jsonl # local artifact index
documents.jsonl
links.jsonl
testing/
runs/
{run_id}/
manifest.json
outputs/
debug/
data/lake/ stores canonical local JSONL datasets.data/lake/paper_metadata.jsonl is the canonical metadata index and dedupedata/artifacts/intake/pdfs/ is a manual staging area for PDFs obtaineddata/lake/paper_pdf_links.jsonl stores the append-only metadata-to-PDFdata/artifacts/ stores physical payloads such as PDFs and Markdown.data/artifacts/victus-data/ stores one primary file per paper per stage fordata/artifacts/victus-ops/ stores compact operational artifacts by run whendata/runtime/runs/{run_id}/ stores compact execution state.data/runtime/outbox/ stores local delivery records for secondary sinks suchdata/debug/runs/{run_id}/ stores debug payloads that are useful for auditdata/registry/ stores artifact manifests and compatibility indexes.data/testing/runs/{run_id}/ isolates testing execution from production lakerun_id must exist before a PipelineEvent is emitted.PipelineRun and PipelineEvent are append-only audit records.paper_stage_state.jsonl stores current operational state by paper_id andstage; consumers must treat the latest record per natural key as current.PipelineEvent.Legacy runtime outputs were archived under:
data/legacy/archive/{date}/
New writes must target the canonical layout. Legacy paths may be read only by
explicit recovery or migration tooling.