Skip to content

Artifact Ingest

This document defines how DropBoxMini accepts, validates, stores, and exposes artifacts published by Orchestrator and other authorized producers.

DropBoxMini acts as the delivery and storage boundary for artifact transfer within the Oryvin ecosystem. Its role is not to decide workflow intent or coordinate multi-step automation. Its role is to receive artifacts, validate requests, store them predictably, and make them available for retrieval.

This document describes the ingest side of the artifact contract.

Purpose

The ingest workflow exists to support several goals:

  • accept published artifacts from authorized producers
  • validate artifact metadata and payload structure
  • store artifacts in predictable locations
  • expose artifacts for later retrieval
  • return explicit success and failure results to producers

This keeps artifact transport and storage separate from workflow execution logic.

Participating components

Producer

A producer is a system that creates and publishes an artifact to DropBoxMini.

Typical producers include:

  • Orchestrator
  • build automation processes
  • documentation publishing workflows

The producer is responsible for:

  • creating the artifact payload
  • generating the manifest
  • authenticating to DropBoxMini
  • uploading the artifact bundle

DropBoxMini

DropBoxMini is responsible for:

  • authenticating the producer request
  • validating the manifest
  • validating the uploaded artifact
  • determining the storage location
  • writing the artifact to storage
  • returning an explicit storage result
  • exposing retrieval paths for stored artifacts

Ingest endpoint

Artifacts are ingested through an authenticated API endpoint.

Canonical endpoint:

POST /api/artifacts

Authentication header:

X-API-Key

Expected request type:

multipart/form-data

Expected parts:

Part Purpose
manifest artifact manifest metadata
artifact artifact bundle or packaged payload

The ingest request must include both required parts.

Authentication

Artifact ingest is restricted to authorized producers.

Authentication is performed using an API key presented in the request header.

Example:

X-API-Key: <shared-key>

If authentication fails, DropBoxMini must reject the request and return an explicit unauthorized response.

DropBoxMini should not attempt to infer producer identity from the payload alone.

Accepted artifact types

The initial ingest contract should support a limited set of artifact categories.

Type Purpose
patch source changes, overlays, or code patch deliveries
build compiled application outputs
doc generated documentation or publication bundles
config configuration or deployment payloads

Requests for unsupported artifact types should be rejected explicitly.

Manifest validation

The manifest is the canonical metadata record for the artifact and must be validated before the artifact is accepted.

Required manifest fields:

Field Purpose
artifact_id unique identifier for the artifact
type artifact category
system owning system, such as weic or orchestrator
producer name of the publishing service
created_utc UTC timestamp of artifact creation
description human-readable description
version patch number, version, or build identifier
files list of payload files included in the artifact

Validation rules include:

  • required fields must be present
  • type must be supported
  • system must be non-empty
  • version must be non-empty
  • files must be present as a list
  • manifest JSON must parse successfully

If validation fails, the request must be rejected before storage occurs.

Artifact structure

Artifacts should be uploaded as a packaged bundle.

Recommended structure:

artifact.zip
├─ manifest.json
└─ payload/

The uploaded artifact must be internally consistent with the manifest.

At minimum, DropBoxMini should verify that:

  • the payload exists
  • referenced files are present
  • the artifact can be stored successfully

More advanced validation such as checksum validation or signature verification may be added later.

Storage model

DropBoxMini stores accepted artifacts using a predictable path structure derived from the manifest.

Recommended storage layout:

dropbox/
├─ weic/
│  ├─ patches/
│  ├─ builds/
│  └─ docs/
├─ orchestrator/
└─ infrastructure/

Typical final path pattern:

dropbox/<system>/<type-plural>/<version>/

Example:

dropbox/weic/patches/0358/

This storage layout makes retrieval, retention, and operational review easier to manage.

Latest resolution

For common retrieval scenarios, DropBoxMini may expose a logical latest selector for artifact types where that is useful.

Examples:

GET /api/artifacts/weic/patches/latest
GET /api/artifacts/weic/builds/latest

The meaning of latest should be deterministic.

Recommended initial rule:

  • latest = most recently stored artifact for the requested system and type

Future versions may refine this to support promotion states or explicit channel rules.

Ingest success response

On successful ingest, DropBoxMini should return an explicit storage result.

Example:

{
  "status": "stored",
  "artifact_id": "20260315-001",
  "path": "/dropbox/weic/patches/0358"
}

Typical success fields:

  • storage status
  • artifact identifier
  • final storage path

This response allows the producer to log publication results and continue downstream processing if needed.

Failure responses

DropBoxMini should return explicit failure results rather than silent or ambiguous failures.

Typical failure conditions include:

  • missing or invalid API key
  • missing manifest
  • missing artifact payload
  • invalid manifest JSON
  • unsupported artifact type
  • inconsistent payload structure
  • storage failure
  • duplicate or conflicting version rules

Typical response classes may include:

Condition Response
authentication failure 401 Unauthorized
invalid request 400 Bad Request
unsupported artifact type 400 Bad Request
storage conflict 409 Conflict
storage failure 500 Internal Server Error

Failure responses should include enough information for the producer to record the reason for failure.

Overwrite and conflict rules

The initial ingest model should avoid silent overwrites.

Recommended behavior:

  • if the target version path already exists, reject the upload
  • require a new version identifier for a replacement artifact
  • make overwrite behavior an explicit future capability rather than a default

This protects traceability and avoids accidental loss of previously stored artifacts.

Retrieval endpoints

Stored artifacts should be retrievable through simple and predictable endpoints.

Examples:

GET /api/artifacts/weic/patches/0358
GET /api/artifacts/weic/patches/latest
GET /api/artifacts/weic/builds/20260315.1

Retrieval may return either:

  • the artifact bundle directly
  • a structured metadata response that points to the stored artifact

The important requirement is predictability of lookup and retrieval.

Logging and traceability

Each ingest request should be logged with enough detail to support operational review.

Recommended logged fields:

  • request timestamp
  • producer identity or authenticated key label
  • artifact_id
  • system
  • artifact type
  • version
  • result status
  • final storage path or failure reason

This supports operational troubleshooting and auditability.

Retention

Initial retention behavior may remain simple.

Recommended initial model:

  • retain all stored artifacts by default
  • do not delete artifacts automatically
  • defer retention pruning rules until artifact volume or operational policy requires them

This is the safest initial approach while the contract is stabilizing.

Responsibilities and boundaries

DropBoxMini should do

  • authenticate ingest requests
  • validate manifest structure
  • validate artifact presence
  • store artifacts predictably
  • expose retrieval paths
  • report ingest results clearly

DropBoxMini should not do

  • determine workflow intent
  • coordinate multi-step automation
  • replace Orchestrator execution logic
  • silently rewrite artifact metadata
  • silently overwrite stored artifacts

This keeps DropBoxMini focused on artifact ingest and delivery.

Relationship to the Oryvin plan

DropBoxMini ingest is a core integration point in the Oryvin lifecycle.

Documentation and intent
        ↓
Orchestrator workflow execution
        ↓
Artifact publication
        ↓
DropBoxMini ingest and storage
        ↓
Target retrieval and consumption

This is one of the key handoff points that allows Oryvin to function as a connected platform rather than a collection of isolated tools.