---
title: "Artifacts are content-addressed: managed blobs plus external references"
canonical: https://skift.stead.ing/docs/adrs/003-artifacts-are-content-addressed/
site: skift
---

# Artifacts are content-addressed: managed blobs plus external references

## Context and Problem Statement

Work produces outputs beyond text: pull requests, patch sets, zips of design assets, bundles of markdown. Downstream agents consume them as inputs. Every project management system supports attachments, but skift runs in a distributed setting where agents on different machines produce and consume. How are artifacts stored and delivered without turning skift into a distributed filesystem, and without pushing storage onto every orchestrator?

## Decision Drivers

- Downstream agents must be able to discover and verify upstream outputs
- Orchestrators should not each solve storage; that creates sprawl and configuration
- Large data must not flow through the project management system
- Existing platform services: git hosting, an OCI registry, one PostgreSQL

## Considered Options

1. References only: skift stores URIs and digests, never bytes
2. Managed blob store only: everything uploaded to skift
3. Both: a managed, size-capped, content-addressed blob store behind a storage interface, plus first-class external references

## Decision Outcome

Chosen option: **both**, because attachments are commonplace and centralizing them prevents sprawl, while a size cap and content addressing keep skift from becoming a data transport. Coding agents already produce git refs and design agents can push to an OCI registry; those stay where they are and skift records a digest.

The artifact shape follows A2A: name, description, parts, metadata. A part is inline text under a cap, a managed blob, or a reference. Every blob and reference carries a digest.

- **Managed blobs**: immutable, content-addressed, size-capped per organization. Storage backend is an interface. Filesystem first, object storage later.
- **References**: `git` for branches, commits, and pull requests. `oci` for arbitrary blobs in a registry, pushed with ORAS. `https` as a fallback. The scheme is the contract and the client resolves it.

### Consequences

- **Good**: Downstream agents verify what they pulled by digest regardless of transport.
- **Good**: Orchestrators need no storage configuration. Small outputs go to skift, large ones to the registry.
- **Good**: OCI artifacts are deduplicated, signable with cosign, and already operated in the platform zone.
- **Bad**: Two artifact paths to document and test.
- **Bad**: A reference can point somewhere a given client cannot reach. Mitigated by scheme conventions, not by skift proxying.
- **Neutral**: Attachments and comments are a surface a swarm can abuse as a message board. Size caps and policy are the controls, and this is tracked as an open discussion.

## Rejected Options

### References only

- **Good**: Simplest service.
- **Bad**: Every orchestrator must solve storage. Sprawl.

### Managed blobs only

- **Good**: One path.
- **Bad**: Skift becomes the transport for large data and the git and OCI content that already has a home gets copied.

## More Information

Revisit size caps and backend choice when the first object storage deployment happens.