generated from coulomb/repo-seed
tegwick
747afc27a6
Aligns the v1 architecture with the longer-horizon platform thesis so we can start implementation without the schema-level inconsistencies the prior review surfaced. ADRs (docs/adr/0001..0006): content-addressed dual-digest storage, append-only event log as source of truth, canonical CBOR manifests, control/data-plane contract, v1 tech stack (Python 3.12 / uv / FastAPI / SQLAlchemy Core + asyncpg / Alembic / cbor2 / blake3 / ruff / mypy / pytest / typer), OCI compatibility kept reachable. Architecture blueprint rewritten to v2: library-first (ffmpeg-shaped) module layout, materialised-view data model over the event log, upload-session and event-stream endpoints pinned, retrieval tiering promoted into the schema. Roadmap added (docs/ROADMAP.md) with three phases. WP-0001 rewritten as the Foundation plan (scaffold + kernels + local FS + minimal app). WP-0002..0005 created carrying the existing state_hub_task_ids forward semantically: ingestion API (T004), retention lifecycle (T005), S3-compatible backend (T006), guide-board pilot (T007). T001/T002/T003/T008 remain in WP-0001 with refined acceptance. README and AGENTS.md refreshed to reflect the new repo shape. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
147 lines
4.4 KiB
Markdown
147 lines
4.4 KiB
Markdown
---
|
|
id: ARTIFACT-STORE-WP-0005
|
|
type: workplan
|
|
title: "Guide-Board Pilot Ingestion"
|
|
repo: artifact-store
|
|
domain: stack
|
|
status: planned
|
|
owner: codex
|
|
topic_slug: stack
|
|
planning_priority: high
|
|
planning_order: 5
|
|
created: "2026-05-15"
|
|
updated: "2026-05-15"
|
|
---
|
|
|
|
# ARTIFACT-STORE-WP-0005: Guide-Board Pilot Ingestion
|
|
|
|
## Purpose
|
|
|
|
Wire the first real producer end-to-end. A guide-board CMIS
|
|
assessment run directory is registered as one artifact package, its
|
|
files are stored through a configured backend, retention is applied,
|
|
and Statehub records a stable package id and summary without storing
|
|
bytes itself. This is the pilot success criterion in INTENT.md.
|
|
|
|
## Constraints
|
|
|
|
- WP-0001 — WP-0004 must be done.
|
|
- `docs/ARCHITECTURE-BLUEPRINT.md` guide-board manifest fields.
|
|
- No guide-board-specific code lives in `artifactstore.registry`;
|
|
pilot-specific glue lives in `artifactstore.pilots.guide_board` or
|
|
in a separate small package.
|
|
|
|
## Prerequisites
|
|
|
|
- WP-0001, WP-0002, WP-0003 done. WP-0004 only required for the
|
|
production target; local FS is sufficient for the pilot test.
|
|
|
|
## D5.1 - Pilot Metadata Schema Registration
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T001
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "eb822821-353c-4cd2-95bf-acb2f084b7ea"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- A JSON Schema for `guide-board.run.v1` package metadata is checked
|
|
in under `schemas/guide-board.run.v1.json`.
|
|
- A bootstrap script registers it via `POST /metadata-schemas`
|
|
(an endpoint added in this workplan).
|
|
- Required keys: `run_id`, `target_profile_ref`,
|
|
`assessment_profile_ref`, `result_status`, `source_commits`
|
|
(object of slug → SHA), `report_paths`, `evidence_counts`,
|
|
`finding_counts`.
|
|
|
|
## D5.2 - Pilot Ingest Helper (CLI + Library Function)
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T002
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- `artifactstore guide-board ingest <run-dir>` walks a guide-board
|
|
run directory, builds the package metadata from `run.json` and
|
|
`retention-summary.json`, uploads every file declared in the
|
|
assessment package manifest (and the manifest itself), and
|
|
finalises the package.
|
|
- Library entry point `pilots.guide_board.ingest_run(path, ...)`
|
|
exposes the same behaviour for embedding.
|
|
- Output: the package id (UUID) and the package manifest digest
|
|
(`blake3:<hex>`).
|
|
|
|
## D5.3 - Fixture-Based Test
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T003
|
|
status: todo
|
|
priority: high
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- A trimmed-down guide-board run fixture (under 1 MB total) lives in
|
|
`tests/fixtures/guide-board/` with realistic file shapes:
|
|
`run.json`, `retention-summary.json`,
|
|
`reports/assessment-package.json`, `reports/report.md`, one
|
|
scorecard, one log-review summary, and a couple of raw artifact
|
|
files.
|
|
- The test runs the CLI / library helper end-to-end against an
|
|
in-memory SQLite + tempdir local backend, then verifies:
|
|
1. package id returned,
|
|
2. manifest digest stable across two runs of the same fixture,
|
|
3. every file downloadable with correct bytes,
|
|
4. retention class applied as configured.
|
|
|
|
## D5.4 - Statehub Linkage Recipe
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T004
|
|
status: todo
|
|
priority: medium
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- `docs/OPERATOR.md` (or a new `docs/pilots/guide-board.md`)
|
|
documents the exact `POST /progress/` or `record_decision` call
|
|
shape Statehub clients should use to link a guide-board run to
|
|
its artifact-store package id and manifest digest.
|
|
- A reference Statehub client snippet is checked in, parameterised
|
|
by env vars.
|
|
|
|
## D5.5 - Operator Smoke Procedure For The Real Producer
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0005-T005
|
|
status: todo
|
|
priority: medium
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- A documented procedure ingests a real (non-fixture) guide-board run
|
|
produced from `~/guide-board` / `~/open-cmis-tck`.
|
|
- Procedure includes: starting `make dev`, registering the schema,
|
|
running the ingest CLI, verifying the manifest, and
|
|
recording the package id in Statehub.
|
|
- Procedure runs end-to-end on a developer workstation under 5
|
|
minutes.
|
|
|
|
## Success criteria
|
|
|
|
- A real guide-board CMIS run is ingested with one CLI invocation.
|
|
- The package manifest lists every stored file with both digests and
|
|
the canonical CBOR digest of the manifest itself.
|
|
- Statehub records the package id and summary; no artifact bytes
|
|
live in Statehub.
|
|
- Retention can be extended on the package without touching bytes.
|
|
- The pilot path validates the storage adapter swap: the same
|
|
command works against `local` and against `s3` (if WP-0004 done).
|