generated from coulomb/repo-seed
tegwick
f90c761ef6
docs/OPERATOR.md (new): runbook with prerequisites, quick start, environment variables, SQLite + PostgreSQL setup, storage layout, CLI reference, HTTP /health reference, an end-to-end Python smoke test (create_package -> ingest_file -> finalize -> manifest), the replay / disaster-recovery procedure, common failure modes, and a References section that links every ADR (0001..0006), the blueprint, platform ambition, roadmap, and assembly experiment. README.md: refreshed to v0.1 baseline status. Quick-start uses the real flow (uv sync, migrate-fresh, dev, /health, artifactstore health). Make targets and CLI commands tabulated. Links docs/OPERATOR.md. AGENTS.md: Current Repo Shape now reflects the landed scaffold + library + CLI + HTTP app rather than "no runnable scaffold yet"; links OPERATOR.md and lists the canonical local commands. workplans/ARTIFACT-STORE-WP-0001-service-baseline.md: - T008 marked done. - frontmatter status: active -> done; updated: 2026-05-16. All ten WP-0001 tasks are now done (T001/T002/T003/T008/T009/T010/ T011/T012/T013/T014). Foundation workplan retires. Gates: ruff clean, mypy --strict clean, 83 tests pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# 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.
|