artifact-store/workplans/ARTIFACT-STORE-WP-0002-ingestion-api.md

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

id	type	title	repo	domain	status	owner	topic_slug	planning_priority	planning_order	created	updated
ARTIFACT-STORE-WP-0002	workplan	Ingestion API And Manifest Surface	artifact-store	stack	planned	codex	stack	high	2	2026-05-15	2026-05-15

ARTIFACT-STORE-WP-0002: Ingestion API And Manifest Surface

Purpose

Expose the WP-0001 library as a complete HTTP API. Producers can create packages, ingest files (single-shot or via the upload-session resource shape), finalise to produce a manifest, list and search packages, download files, and tail the event stream.

Constraints

• ADR-0001, ADR-0002, ADR-0003, ADR-0004, ADR-0005, ADR-0006.
• docs/ARCHITECTURE-BLUEPRINT.md API shape section.
• All handlers must be thin: translate transport → registry.* calls.

Prerequisites

• WP-0001 done (library is functional against local backend).

D2.1 - Package CRUD Endpoints

id: ARTIFACT-STORE-WP-0002-T001
status: todo
priority: high
state_hub_task_id: "e3879111-4be9-4731-8aea-15abb874f960"

Acceptance:

• POST /packages, GET /packages (filterable by producer / subject / retention_class / metadata key), GET /packages/{id}, POST /packages/{id}/files (single-shot multipart), POST /packages/{id}/finalize.
• GET /packages/{id}/manifest (Accept: application/cbor) and GET /packages/{id}/manifest.json (JCS projection).
• Validation errors return RFC 7807 problem documents.
• OpenAPI is generated automatically (FastAPI default) and served at /openapi.json + /docs.

D2.2 - File Download And Range Reads

id: ARTIFACT-STORE-WP-0002-T002
status: todo
priority: high

Acceptance:

• GET /files/{file_id} returns metadata.
• GET /files/{file_id}/download streams bytes; supports Range request headers (single contiguous range; multi-range is out of scope for v1).
• ETag is the file's primary content address; If-None-Match returns 304.
• Streaming uses AsyncIterator[bytes] end-to-end; no full-file buffering.

D2.3 - Upload Session Resource (Wire Shape Pinned)

id: ARTIFACT-STORE-WP-0002-T003
status: todo
priority: medium

Acceptance:

• POST /uploads opens a session, returns an upload id and content upload URL.
• PATCH /uploads/{upload_id} accepts a body with Content-Range; v1 implementation may accept the whole body in one call.
• POST /uploads/{upload_id}/complete promotes the upload into a file under a given package id and relative path.
• Implementation is allowed to be single-shot internally; the wire shape and resource lifecycle must be the final one (per PLATFORM-AMBITION A6).

D2.4 - Event Stream Long-Poll

id: ARTIFACT-STORE-WP-0002-T004
status: todo
priority: medium

Acceptance:

• GET /events?since=<sequence>&limit=N returns events in order with a long-poll wait when the tail is reached.
• Events are CBOR by default; Accept: application/json returns the JCS projection of each event payload.
• Test: a consumer that tails from sequence 1 never misses an event produced during the test.

D2.5 - Auth Scaffolding (Shared-Secret Bearer)

id: ARTIFACT-STORE-WP-0002-T005
status: todo
priority: medium

Acceptance:

• Bearer token auth on all mutating endpoints; configurable per-tenant token list via env / config file.
• Read endpoints are also gated by default; an explicit ARTIFACTSTORE_ANON_READ=true opt-in for dev.
• Health endpoint remains anonymous.

D2.6 - Integration Tests Through The Full HTTP Surface

id: ARTIFACT-STORE-WP-0002-T006
status: todo
priority: high

Acceptance:

• httpx-based test suite exercises every endpoint.
• A scripted test ingests a 50-file package, finalises it, downloads every file, verifies digests, and tails events.
• A property-based test fuzzes the upload session lifecycle.

Success criteria

• A producer can run the full ingest-and-retrieve flow against make dev with curl.
• All blueprint endpoints in the v1 native surface are implemented.
• The CLI gains artifactstore push <dir> and artifactstore manifest <package_id> subcommands as thin clients over the HTTP API.