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