# 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](docs/adr/0002-event-log-source-of-truth.md)); 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`](https://docs.astral.sh/uv/).

```sh
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

```sh
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](INTENT.md) — purpose, product thesis, scope, boundary.
- [SCOPE.md](SCOPE.md) — lightweight orientation.
- [docs/OPERATOR.md](docs/OPERATOR.md) — runbook: env vars, DB backends,
  CLI / HTTP reference, end-to-end smoke test, replay procedure.
- [docs/ARCHITECTURE-BLUEPRINT.md](docs/ARCHITECTURE-BLUEPRINT.md) — v2
  architecture: modules, data model, API shape.
- [docs/PLATFORM-AMBITION.md](docs/PLATFORM-AMBITION.md) — longer-horizon
  thesis and v1 schema commitments.
- [docs/ROADMAP.md](docs/ROADMAP.md) — workplan sequencing across phases.
- [docs/adr/](docs/adr/) — architecture decision records (ADR-0001 …
  ADR-0006).
- [docs/ASSEMBLY-EXPERIMENT.md](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](workplans/ARTIFACT-STORE-WP-0001-service-baseline.md) — **done**
- [WP-0002 — Ingestion API and manifest surface](workplans/ARTIFACT-STORE-WP-0002-ingestion-api.md) (planned)
- [WP-0003 — Retention lifecycle](workplans/ARTIFACT-STORE-WP-0003-retention-lifecycle.md) (planned)
- [WP-0004 — S3-compatible backend](workplans/ARTIFACT-STORE-WP-0004-s3-compatible-backend.md) (planned)
- [WP-0005 — Guide-board pilot ingestion](workplans/ARTIFACT-STORE-WP-0005-guide-board-pilot.md) (planned)

## Agent operating notes

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