artifact-store/workplans/ARTIFACT-STORE-WP-0001-service-baseline.md

id, type, title, repo, domain, status, owner, topic_slug, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	repo	domain	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
ARTIFACT-STORE-WP-0001	workplan	Artifact Store Service Baseline	artifact-store	stack	active	codex	stack	high	1	2026-05-15	2026-05-15	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

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

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

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

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

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

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

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

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

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.