artifact-store

Generic artifact registry and storage gateway for generated outputs, evidence packages, reports, logs, snapshots, exports, and release artifacts.

The registry owns artifact identity, metadata, provenance, retention policy, and retrieval records. Bytes are delegated to configured storage backends (local filesystem in v1, S3-compatible / Ceph RGW in WP-0004).

The shape is library-first (artifactstore Python package); the HTTP server and the CLI are thin consumers. Content is addressed by digest; state is authoritative in an append-only event log (ADR-0002); materialised views are rebuildable.

Status

v0.1 (WP-0001 baseline) — library, CLI, minimal HTTP app, local FS backend, end-to-end ingest + finalize + replay all working. The full package CRUD HTTP API lands in WP-0002.

Quick start

Requires Python ≥ 3.12 and uv.

uv sync --all-extras          # install dependencies (creates .venv + uv.lock)
cp .env.example .env          # optional; defaults work out of the box

make migrate-fresh            # initialise ./var/artifactstore.db
make dev                      # uvicorn on 127.0.0.1:8000

# in another terminal
curl -s http://127.0.0.1:8000/health | python3 -m json.tool
artifactstore health

Make targets

Target	Purpose
make install	uv sync --all-extras
make dev	run the FastAPI app with reload
make test	run the pytest suite
make lint	ruff check + ruff format --check
make format	apply ruff format + ruff check --fix
make type	mypy --strict
make migrate	alembic upgrade head
make migrate-fresh	drop the local SQLite DB and re-run migrations
make clean	remove caches and build artefacts

CLI

artifactstore version     # print the package version
artifactstore migrate     # alembic upgrade head
artifactstore replay      # rebuild materialised views from the event log
artifactstore health      # JSON liveness summary (same payload as /health)

Documentation

• INTENT.md — purpose, product thesis, scope, boundary.
• SCOPE.md — lightweight orientation.
• docs/OPERATOR.md — runbook: env vars, DB backends, CLI / HTTP reference, end-to-end smoke test, replay procedure.
• docs/ARCHITECTURE-BLUEPRINT.md — v2 architecture: modules, data model, API shape.
• docs/PLATFORM-AMBITION.md — longer-horizon thesis and v1 schema commitments.
• docs/ROADMAP.md — workplan sequencing across phases.
• docs/adr/ — architecture decision records (ADR-0001 … ADR-0006).
• docs/ASSEMBLY-EXPERIMENT.md — opt-in research line on hand-tuned asm for hot kernels.

Workplans

• WP-0001 — Foundation: scaffold, core kernels, local FS backend — done
• WP-0002 — Ingestion API and manifest surface (planned)
• WP-0003 — Retention lifecycle (planned)
• WP-0004 — S3-compatible backend (planned)
• WP-0005 — Guide-board pilot ingestion (planned)

Agent operating notes

See AGENTS.md for the StateHub-integrated session protocol, workplan conventions, and progress-logging contract.