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>
3.6 KiB
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.