generated from coulomb/repo-seed
230 lines
7.0 KiB
Markdown
230 lines
7.0 KiB
Markdown
---
|
|
id: ARTIFACT-STORE-WP-0001
|
|
type: workplan
|
|
title: "Artifact Store Service Baseline"
|
|
repo: artifact-store
|
|
domain: stack
|
|
status: active
|
|
owner: codex
|
|
topic_slug: stack
|
|
planning_priority: high
|
|
planning_order: 1
|
|
created: "2026-05-15"
|
|
updated: "2026-05-15"
|
|
state_hub_workstream_id: "aebf996c-8721-4e8c-9e56-61d5e4bf8dcb"
|
|
---
|
|
|
|
# ARTIFACT-STORE-WP-0001: Artifact Store Service Baseline
|
|
|
|
## Purpose
|
|
|
|
Implement the first usable artifact registry and storage gateway. The service
|
|
should preserve artifact packages, index their metadata, delegate bytes to a
|
|
configured storage backend, apply default retention rules, and expose stable
|
|
package identifiers that Statehub and producer repositories can link to.
|
|
|
|
The first producer target is a guide-board assessment run, including OpenCMIS TCK
|
|
reports and raw assessment artifacts.
|
|
|
|
## Background
|
|
|
|
Guide-board can already produce self-contained run directories with retention
|
|
summaries, assessment packages, raw artifacts, scorecards, and log reviews. Those
|
|
directories should not live only in `/tmp`, and committing raw evidence into
|
|
producer repositories is the wrong long-term shape.
|
|
|
|
`artifact-store` becomes the shared preservation layer:
|
|
|
|
- producers generate files,
|
|
- artifact-store registers and stores them,
|
|
- Statehub records the work outcome and links to the registry package,
|
|
- storage backends handle durable bytes.
|
|
|
|
Ceph is the likely self-hosted production backend through its S3-compatible RGW
|
|
interface, but the service must keep the backend interface generic.
|
|
|
|
## Target Architecture
|
|
|
|
```text
|
|
producer package
|
|
-> registry API
|
|
-> metadata database
|
|
-> retention policy engine
|
|
-> storage adapter
|
|
-> local filesystem or S3-compatible object storage
|
|
```
|
|
|
|
## Boundary
|
|
|
|
This workplan owns the first service implementation and API contract. It does
|
|
not need to build a UI, implement cold-storage restore tiers, replace Statehub,
|
|
or provide formal records-management certification.
|
|
|
|
## D1.1 - Service Scaffold And Repository Identity
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0001-T001
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "84209430-ec3b-4c5e-924e-019c25434230"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Replace the seed README with artifact-store service instructions.
|
|
- Add a Python service scaffold with a clear package/module layout.
|
|
- Provide a local development command.
|
|
- Provide a test command.
|
|
- Keep generated artifact bytes and local databases ignored by git.
|
|
- Document required environment variables.
|
|
|
|
## D1.2 - Registry Data Model
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0001-T002
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "e5249a39-46a2-4b56-813e-0339c52cd14e"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Define persistent models for artifact packages, files, storage locations,
|
|
retention rules, retention events, and audit events.
|
|
- Store package metadata as structured JSON while keeping core query fields
|
|
explicit.
|
|
- Record package lifecycle status: created, uploading, finalized, deleted, and
|
|
failed.
|
|
- Record file `sha256`, size, media type, and logical relative path.
|
|
- Add migrations or a reproducible schema initialization path.
|
|
|
|
## D1.3 - Local Filesystem Storage Backend
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0001-T003
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "68f9a752-0012-4cc1-8768-ec3f75295e7a"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Implement a storage adapter interface.
|
|
- Implement a local filesystem backend for development and tests.
|
|
- Store objects under deterministic package/file keys.
|
|
- Prevent path traversal and accidental writes outside the configured storage
|
|
root.
|
|
- Add backend health reporting.
|
|
- Add tests for put, get, head, and delete operations.
|
|
|
|
## D1.4 - Package Ingestion API
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0001-T004
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "e3879111-4be9-4731-8aea-15abb874f960"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Add endpoints to create a package, upload files, finalize a package, retrieve
|
|
package metadata, list packages, and download files.
|
|
- Compute file hashes server-side during ingestion.
|
|
- Reject duplicate logical paths within one package unless explicitly replacing
|
|
a non-finalized file.
|
|
- Produce a package manifest after finalization.
|
|
- Add API tests covering successful ingestion and validation failures.
|
|
|
|
## D1.5 - Retention Baseline
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0001-T005
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "2d6cbd83-c348-45ad-a223-7870a3412225"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Seed default retention classes for transient, raw-evidence, summary-evidence,
|
|
release-evidence, and permanent-record.
|
|
- Apply a default `expires_at` when a package is created or finalized.
|
|
- Add endpoints to extend retention and apply or release holds.
|
|
- Record retention changes as retention events and audit events.
|
|
- Expose deletion eligibility without deleting bytes automatically in the first
|
|
implementation.
|
|
|
|
## D1.6 - S3-Compatible Backend Design Hook
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0001-T006
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "7b980a55-2364-48c3-98ac-081629a8d2b7"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Define configuration fields for an S3-compatible backend.
|
|
- Keep the adapter contract compatible with Ceph RGW.
|
|
- Add an implementation stub or feature-flagged backend if dependencies are not
|
|
ready.
|
|
- Document expected Ceph/S3 configuration without requiring a live Ceph service
|
|
for baseline tests.
|
|
|
|
## D1.7 - Guide-Board Pilot Ingestion
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0001-T007
|
|
status: todo
|
|
priority: high
|
|
state_hub_task_id: "eb822821-353c-4cd2-95bf-acb2f084b7ea"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Provide a CLI helper or documented curl flow to register a guide-board run
|
|
directory as one package.
|
|
- Preserve guide-board run metadata: run id, target profile, assessment profile,
|
|
evidence result counts, finding counts, source commits, and report paths.
|
|
- Ingest the CMIS pilot run shape, including scorecard and log-review reports.
|
|
- Return a package id suitable for recording in Statehub.
|
|
- Add a fixture-based test that does not require the real OpenCMIS TCK.
|
|
|
|
## D1.8 - Operator Documentation And Handoff
|
|
|
|
```task
|
|
id: ARTIFACT-STORE-WP-0001-T008
|
|
status: todo
|
|
priority: medium
|
|
state_hub_task_id: "9b60036c-61f2-4c22-ad31-7213473d42d0"
|
|
```
|
|
|
|
Acceptance:
|
|
|
|
- Document local run, test, and package ingestion commands.
|
|
- Document retention behavior and extension flow.
|
|
- Document the boundary between artifact-store and Statehub.
|
|
- Include a dev-agent handoff section listing the first implementation order.
|
|
- Keep architecture docs aligned with the implemented API.
|
|
|
|
## Suggested Implementation Order
|
|
|
|
1. Service scaffold, test harness, and README.
|
|
2. Metadata models and local database setup.
|
|
3. Local filesystem storage adapter.
|
|
4. Package create/upload/finalize/download API.
|
|
5. Retention defaults, extension, hold, and audit events.
|
|
6. Guide-board run ingestion helper.
|
|
7. S3-compatible backend configuration and Ceph notes.
|
|
|
|
## First Pilot Success Criteria
|
|
|
|
- A completed guide-board CMIS run can be ingested from a local directory.
|
|
- The package manifest lists every stored file with SHA-256 and size.
|
|
- The registry returns a stable package id.
|
|
- Files can be downloaded through the service.
|
|
- Default retention is visible and can be extended.
|
|
- Statehub can record the package id and summary without storing artifact bytes.
|