# 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 next).

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; materialised views
are rebuildable.

## Status

Scaffold landed. The core kernels and local FS backend follow in the
remaining tasks of [WP-0001](workplans/ARTIFACT-STORE-WP-0001-service-baseline.md).

## Develop

Requires Python ≥ 3.12 and [`uv`](https://docs.astral.sh/uv/) on the path.

```sh
make install        # uv sync --all-extras
cp .env.example .env

make dev            # uvicorn artifactstore.api.http:app --reload
make test           # pytest
make lint           # ruff check + ruff format --check
make type           # mypy --strict
make migrate        # alembic upgrade head (configured in WP-0001-T002)
```

The dev server listens on `127.0.0.1:8000`. The scaffold root route
returns `{"service": "artifact-store", "status": "scaffold"}`; the real
`/health` endpoint lands in `WP-0001-T014`.

## Documentation

- [INTENT.md](INTENT.md) — purpose, product thesis, scope, boundary.
- [SCOPE.md](SCOPE.md) — lightweight orientation.
- [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.
- [docs/ASSEMBLY-EXPERIMENT.md](docs/ASSEMBLY-EXPERIMENT.md) — opt-in
  research line on hand-tuned asm for hot kernels.

## Active workplans

- [WP-0001 — Foundation: scaffold, core kernels, local FS backend](workplans/ARTIFACT-STORE-WP-0001-service-baseline.md)
- [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.