This hub is the source of truth for stable guarantees that future changes must
preserve.
Contracts are high-trust documentation. Agents should treat them as
compatibility boundaries before changing paths, artifacts, identities, schemas,
or stage handoffs.
Contracts are split by source and responsibility:
docs/contracts/fundamental/: ecosystem-level contracts synchronized from
victus-docs. These define shared Victus interfaces and preserve the central
contract repository subdirectory layout.docs/contracts/local/: repository-specific contracts owned here.
- Data Layout: stable local artifact
locations, identities, stage inputs, stage outputs, and failure expectations.
- Metadata Extraction: operation, LLM selection
contract, paper_metadata.jsonl schema, and dedupe rules.
- Stage Handoffs: boundaries between
metadata, bibliography export, manual PDF intake, PDF processing, trimming,
experiment mapping, and canonical evidence extraction.
- Artifact Schemas: durable JSON/JSONL
shapes consumed or produced by the current pipeline.
- Artifact Inventory: complete artifact
list with the inputs consumed to create each artifact.
- Paper Pipeline State: PostgreSQL
lifecycle state for one paper stage attempt.
- Paper Processing State: derived
PostgreSQL dashboard state by paper.
Contracts cover:
- local runtime artifact boundaries;
- stage handoff locations;
- stable identity terms;
- block identity and field-level semantics;
- required validation expectations;
- compatibility boundaries between processing stages;
- config and environment resolution that affects paths or models;
- public CLI command names used by operators and agents;
- schema-level expectations for current durable artifacts and PostgreSQL state;
- experiment map and canonical evidence schema expectations.
- paper classification gate expectations.
- testing workspace artifact expectations.
Contracts do not cover:
- implementation details;
- operational procedures;
- architecture rationale;
- external vendor guarantees.
- downstream analytics schemas outside this repository.
Documentation with status: source-of-truth is authoritative as of its own
updated_at value. If code and docs disagree, stop and reconcile the contract
before making behavior-changing edits.