tegwick
07feabe9cc
Sync AGENTS.md, CLAUDE.md, and .claude/rules from updated project_rules templates: workplan-first session protocol, legacy terminology footnote, and GET /workplans/ examples. |
||
|---|---|---|
| .claude/rules | ||
| .forgejo/workflows | ||
| docs | ||
| migrations | ||
| registry | ||
| schemas | ||
| scripts | ||
| src/artifactstore | ||
| tests | ||
| workplans | ||
| .custodian-brief.md | ||
| .env.example | ||
| .gitignore | ||
| .repo-classification.yaml | ||
| AGENTS.md | ||
| alembic.ini | ||
| CLAUDE.md | ||
| INTENT.md | ||
| LICENSE | ||
| Makefile | ||
| pyproject.toml | ||
| README.md | ||
| SCOPE.md | ||
| uv.lock | ||
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.