This document defines the stable shared contracts owned by victus-infra.
These contracts describe the guarantees that consumer repositories may depend
on when using the shared Victus infrastructure runtime.
Covered contracts:
- S3-compatible artifact storage.
- Postgres registry state.
- Redis Streams event delivery.
- Private DNS names for shared services.
- Ownership boundaries between infrastructure and consumers.
Out of scope:
- application business logic.
- worker implementation details.
- SDK or bridge implementation internals.
- RAG, embeddings, or domain-specific processing guarantees.
- operational procedures for deploying or repairing services.
victus-infra owns:
- shared runtime service definitions.
- shared infrastructure endpoints.
- shared storage buckets and top-level prefixes.
- shared registry schema and database migrations.
- shared event stream names and envelope expectations.
- private DNS names for infrastructure services.
Consumer repositories own:
- application payload semantics.
- worker lifecycle and retry strategy.
- domain-specific artifact contents.
- validation of payloads they produce or consume.
- compatibility with these shared infrastructure contracts.
Consumers must not depend on internal deployment mechanics, container names,
volume names, or Ansible role internals unless a future contract explicitly
promotes those details to stable interfaces.
S3-compatible object storage is provided by SeaweedFS and exposed through the
shared infrastructure runtime.
The declarative bucket source is:
compose/configs/seaweedfs/buckets.json
The following buckets are repository-owned infrastructure buckets:
victus-corpus
victus-rag
victus-backups
victus-tmp
victus-corpus source papers, paper stages, analytics outputs, registry backups
victus-rag RAG-derived staging data, datasets, exports, and temporary work
victus-backups backup artifacts not tied to a single paper prefix
victus-tmp temporary infrastructure-owned objects
victus-corpus owns these top-level prefixes:
papers/
analytics/jobs/
analytics/reports/
analytics/reports/2026-05-11/
registry_backups/
victus-rag owns these top-level prefixes:
staging/
datasets/
exports/
tmp/
Paper-scoped artifacts must live under:
papers/{sha256_hash}/
Expected paper layout:
papers/{sha256_hash}/raw/source.pdf
papers/{sha256_hash}/stages/01_metadata/
papers/{sha256_hash}/stages/02_normalized/
papers/{sha256_hash}/stages/03_docling/
papers/{sha256_hash}/stages/04_claims/
victus-corpus is the stable bucket for source papers and paper stage
artifacts.victus-rag is the stable bucket for RAG-derived artifacts.- Paper-scoped prefixes use a content hash segment and end with
/.
- Infrastructure code may create missing declared buckets and prefixes
idempotently.
- RAG-derived artifacts must not be written as source paper artifacts.
- Source paper artifacts must not depend on consumer-specific storage layouts.
- Temporary objects must not be treated as durable contract outputs.
pipeline-postgres provides the core Postgres runtime endpoint. Application
schemas and table migrations are owned outside this repository.
Database:
victus_registry
Private DNS endpoint:
pipeline-postgres.victus.io:5432
- This repository starts and exposes the Postgres service.
- This repository does not apply application table migrations.
- Service/container naming follows
domain-technology: pipeline-postgres.
- Schema ownership remains outside
victus-infra.
Redis provides a durable operational event stream for shared infrastructure
events.
Private DNS endpoint:
redis.victus.io:6379
Primary stream:
victus:events
Dead letter stream:
victus:events:dead
Producers write events using the following field contract:
event_type stable event name
paper_id paper identifier when the event is paper-scoped
timestamp unix timestamp
payload JSON object encoded as a string
Event names currently reserved by infrastructure:
victus:artifact:done
victus:stage:started
victus:stage:done
victus:error
External consumers must use Redis Streams consumer groups.
Consumers are responsible for:
- creating or joining their consumer group.
- acknowledging processed messages.
- validating event payloads before acting on them.
- recovering state from Postgres when they need durable truth.
- moving invalid messages to the dead letter stream when appropriate.
victus:events is replayable through Redis Streams semantics.- Events require consumer acknowledgement when read through consumer groups.
victus:events:dead is reserved for rejected or unprocessable messages.- Event delivery is operationally durable but does not replace Postgres state.
- Consumers must not assume Redis Pub/Sub semantics.
- Consumers must not use Redis as the durable registry source of truth.
- Invalid consumer-specific payloads should not block the primary stream
indefinitely.
- Acknowledgement means the consumer has accepted responsibility for the
message outcome.
CoreDNS owns private service discovery for shared Victus infrastructure names.
Zone:
victus.io
s3.victus.io
*.s3.victus.io
pipeline-postgres.victus.io
redis.victus.io
litellm.victus.io
langfuse.victus.io
- Shared services should be addressed through private DNS names where
available.
- Consumer repositories should prefer stable DNS names over container names.
- DNS names describe infrastructure service roles, not implementation details.
- Container names are not public contracts.
- Host paths are not service discovery contracts.
- A DNS name must not be repurposed for an incompatible service role.
- Existing bucket names and top-level prefixes should remain backward
compatible unless a decision record documents a migration.
- Database enum changes must preserve compatibility for existing consumers or
include an explicit migration path.
- Event names and required envelope fields should remain stable.
- New contracts should be added explicitly before consumers depend on them.
- Contract-breaking changes require a documented migration path.
- Missing buckets or declared prefixes may be recreated idempotently by
infrastructure tooling.
- Consumers should tolerate duplicate events and use durable state to determine
final outcomes.
- Consumers should recover from missed event reads by querying Postgres.
- Invalid events should be isolated to
victus:events:dead rather than
silently discarded.
- Temporary storage prefixes may be cleaned without preserving consumer state.