artifacts

type ArtifactRef ¶

type ArtifactRef struct {
	ID        string
	MimeType  string
	SizeBytes int64
	Filename  string
	SHA256    string
	Scope     ArtifactScope
	Namespace string
	Source    map[string]any
}

ArtifactRef is the canonical reference returned by Put* and resolved by GetRef. `ID` is content-addressed: `{namespace}_{sha256_hex[:12]}`. Re-uploading identical bytes within the same isolation triple returns the existing ref (no duplicate storage) EVEN WHEN the two Puts carry different `Scope.TaskID` values — so `Scope.TaskID` on a resolved ref is the FIRST writer's stamp, not necessarily the caller's.

`SHA256` carries the full hex digest (64 chars). `SizeBytes` is the length of the stored bytes. `Source` is opaque caller metadata — drivers persist it as-is; for the FS driver, values must be JSON-encodable (non-encodable values cause Put to fail at marshal time).

type ArtifactScope ¶

type ArtifactScope struct {
	TenantID  string
	UserID    string
	SessionID string
	TaskID    string
}

ArtifactScope carries the `(tenant, user, session)` isolation triple that OWNS an artifact plus the `TaskID` provenance annotation that records which task produced it. All four fields are flat strings; the consumer (tool dispatcher) is responsible for translating the runtime's `identity.Quadruple` (whose `RunID` becomes `TaskID`) into this shape.

Mandatory at the API boundary: `TenantID`, `UserID`, `SessionID` must be non-empty for Put*, Get, GetRef, Exists and Delete. Empty `TaskID` is acceptable for session-scoped artifacts, and a populated one never narrows a read — see `Triple`.

func (s ArtifactScope) Equal(other ArtifactScope) bool

func (s ArtifactScope) EqualTriple(other ArtifactScope) bool

func (s ArtifactScope) Triple() ArtifactScope

func (s ArtifactScope) Validate() error

func (s ArtifactScope) ValidateFilter() error

type ArtifactStore ¶

type ArtifactStore interface {
	// PutBytes stores data under scope, returning the canonical ref.
	// The ref's `ID` is `{namespace}_{sha256_hex[:12]}`. Re-Put with
	// identical (triple, namespace, bytes) is a no-op that returns the
	// EXISTING ref — including when the new call carries a different
	// `scope.TaskID`, in which case the returned ref carries the first
	// writer's stamp and nothing is stored under the caller's task.
	PutBytes(ctx context.Context, scope ArtifactScope, data []byte, opts PutOpts) (ArtifactRef, error)

	// PutText is a thin wrapper over PutBytes that stores `text` as
	// UTF-8 bytes. Recovered via Get as bytes. MimeType defaults to
	// `text/plain; charset=utf-8` when opts.MimeType is empty.
	PutText(ctx context.Context, scope ArtifactScope, text string, opts PutOpts) (ArtifactRef, error)

	// Get returns the bytes for `id` within `scope`'s isolation triple.
	// `scope.TaskID` is IGNORED: a caller that stamped a task and a
	// caller that did not read the same artifact. Found-false indicates
	// the ref does not exist under that triple; it is NOT an error.
	// ErrNotFound is reserved for actual error contexts.
	Get(ctx context.Context, scope ArtifactScope, id string) ([]byte, bool, error)

	// GetRef returns the metadata-only ref for `id` within `scope`'s
	// isolation triple. `scope.TaskID` is IGNORED for resolution; the
	// returned `Ref.Scope.TaskID` is the stored provenance stamp, which
	// is the first writer's and may differ from the caller's. Same
	// found-false semantics as Get.
	GetRef(ctx context.Context, scope ArtifactScope, id string) (*ArtifactRef, bool, error)

	// Exists reports whether `id` is stored under `scope`'s isolation
	// triple. `scope.TaskID` is IGNORED. Cheaper than GetRef when the
	// caller only needs presence.
	Exists(ctx context.Context, scope ArtifactScope, id string) (bool, error)

	// Delete removes `id` from `scope`'s isolation triple and returns
	// whether anything existed before delete. `scope.TaskID` is IGNORED,
	// and EVERY stored copy under the triple is removed — a Delete that
	// reported success while leaving a copy a later Get resolves would
	// be the silent degradation CLAUDE.md §13 forbids. Idempotent:
	// Delete on absent returns `(false, nil)`.
	Delete(ctx context.Context, scope ArtifactScope, id string) (bool, error)

	// List returns refs whose scope matches `filter`. `filter.TenantID`
	// is REQUIRED (wrapped `ErrIdentityRequired` otherwise) — an
	// unscoped all-tenants listing is not expressible here. Every other
	// empty field is a wildcard within that tenant:
	// `ArtifactScope{TenantID: "A"}` lists every artifact under tenant A
	// across users / sessions / tasks.
	//
	// THE TaskID FILTER IS LOSSY, AND SAYING SO IS PART OF THE CONTRACT.
	// Because the write key is the isolation triple, two tasks storing
	// identical bytes in one session collapse to ONE artifact carrying
	// the FIRST writer's stamp. So `filter.TaskID = "B"` does not return
	// an artifact whose bytes run B stored, if run A stored them first.
	// This is inherent to a content-addressed store rather than an
	// implementation shortfall: the id is derived from the bytes, so
	// "which run produced these bytes" has no single answer once two
	// runs produce them. `filter.TaskID` answers "which artifacts is
	// this run the recorded producer of", which is a weaker question
	// than "which artifacts did this run write".
	//
	// Order is not specified; callers that need stability sort the
	// returned slice themselves.
	List(ctx context.Context, filter ArtifactScope) ([]ArtifactRef, error)

	// Close releases driver resources. Subsequent calls return
	// wrapped `ErrStoreClosed`. Implementations MUST honour ctx
	// during long teardowns (none of V1's drivers have any).
	Close(ctx context.Context) error
}

ArtifactStore is Harbor's mandatory content-addressed blob store. All eight methods are required; there is no `Supports*` capability ceremony (AGENTS.md §4.4). Implementations MUST be safe for N concurrent goroutines on a single shared instance; the conformance suite's `Concurrent_PutGet_NoRace` is the gate.

Identity is enforced at the API boundary: every Put*/Get/GetRef/ Exists/Delete validates `scope`'s triple before touching storage, and `List` requires at least a tenant.

KEY VERSUS FILTER — the distinction the interface is built on. `Get` / `GetRef` / `Exists` / `Delete` take an IDENTITY: they resolve on `(TenantID, UserID, SessionID, id)` and IGNORE `scope.TaskID`, which is a provenance annotation. `List` takes a PREDICATE over a result set: every empty field below the tenant is a wildcard, `TaskID` included. The two are deliberately different things and the difference is stated here so they stop being accidentally different.

Get / GetRef return `(value, found, err)`. Found-false is NOT an error.

func Open(_ context.Context, cfg config.ArtifactsConfig) (ArtifactStore, error)

func OpenDriver(name string, cfg config.ArtifactsConfig) (ArtifactStore, error)

type Factory ¶

type Factory func(config.ArtifactsConfig) (ArtifactStore, error)

Factory builds an ArtifactStore from an ArtifactsConfig. Drivers expose one Factory each via init() → Register.

type Presigner ¶

type Presigner interface {
	// PresignGet returns a time-bounded HTTPS URL the caller can hand
	// to a downstream consumer for direct download of the artifact's
	// bytes. Read-side only — there is no PresignPut / PresignDelete
	// counterpart at V1 (write-side presigned URLs are an attack
	// surface; documented in the phase plan).
	//
	// Returns a wrapped error when:
	//   - the scope fails identity validation (`ErrIdentityRequired`),
	//   - the artifact does not exist in this scope (`ErrNotFound`),
	//   - `expiry` is out of the `[1 minute, 7 days]` range,
	//   - the underlying signer fails.
	PresignGet(ctx context.Context, scope ArtifactScope, id string, expiry time.Duration) (string, error)
}

Presigner is an OPTIONAL capability interface that backends with native presigned-URL support implement. This is the explicit exception to the "no optional capabilities" rule in AGENTS.md §4.4: only S3-compatible object stores have presigned URLs natively, and the capability cannot be reasonably faked by the other V1 drivers (InMem / FS / SQLite-blob / Postgres-blob) without bolting a separate signing service onto Harbor — which is out of V1 scope.

Per RFC §6.10, presigned URLs are the read-side hand-off path for media-class artifacts: the runtime hands a Console / Protocol client a time-bounded HTTPS URL the client downloads directly from object storage, bypassing the runtime's bytes path entirely.

Callers that need presigned URLs type-assert the `ArtifactStore` they hold to `Presigner`; absence is a typed error (`ErrPresignUnsupported`), not a silent fallback. The S3 driver is the only V1 driver implementing this capability.

Identity is mandatory at the Presigner boundary just like every other ArtifactStore method: implementations MUST validate the `scope` and reject with `ErrIdentityRequired` when any of tenant/user/session is empty.

`expiry` is bounded — implementations MUST reject expiries shorter than 1 minute or longer than 7 days (S3's documented limit). Out- of-range expiries return a clear error rather than being silently clamped (AGENTS.md §5: fail loudly).

type PutOpts ¶

type PutOpts struct {
	MimeType  string
	Filename  string
	Namespace string
	Source    map[string]any
}

PutOpts carries optional metadata for Put* calls.

`Namespace` is a logical bucket that participates in `ID` computation, so the same bytes under different namespaces produce distinct refs. Callers SHOULD provide a namespace; drivers default to `"default"` when empty.

`Filename` is metadata only — never used in path construction. The FS driver's path-safety guard rejects traversal regardless.

`Source` values must be JSON-encodable when targeting the FS driver (it persists `Source` to a sibling `.meta.json`). Use Go primitives, slices, and maps; non-encodable values (functions, channels, cyclic graphs) cause Put to fail at marshal time.

type ScopedArtifacts ¶

type ScopedArtifacts struct {
	// contains filtered or unexported fields
}

ScopedArtifacts is the immutable facade tools and runtime use to access the artifact store. It carries a fixed `ArtifactScope` (set at construction, never mutated) and:

• Auto-stamps the scope on every Put*: callers do not pass scope at the facade boundary, so they cannot accidentally write to a different one.
• Scope-checks on `GetRef`, and ONLY on `GetRef`: if the underlying store returned a ref outside the facade's isolation triple, the facade returns wrapped `ErrScopeMismatch` rather than leaking cross-scope bytes. `Get` / `Exists` / `Delete` / `List` pass straight through — the DRIVERS are the enforcement point, and they resolve on the triple. (This list used to claim all five methods checked; only one ever did. The claim is corrected rather than the other four grown a check they do not need.)

The check compares the ISOLATION TRIPLE, not the whole scope. A ref carries the producing task's `TaskID` as a provenance stamp, and a facade constructed without one — the ordinary case for a tool reading back what an earlier run in the same session wrote — must not read that stamp as a mismatch. Comparing the full scope here would refuse exactly the read the triple-keyed store exists to allow.

Construction fails loud: `NewScoped` panics when the scope fails `Validate`. The facade's invariant is "every operation has a valid fixed scope"; rejecting at construction is the simplest, loudest failure mode (AGENTS.md §5: "fail loudly"). Acceptable per design — the alternative (returning an error from a constructor on every call site) accumulates boilerplate that masks the actual bug: callers that built a facade without a complete identity triple.

func NewScoped(store ArtifactStore, scope ArtifactScope) *ScopedArtifacts

func (s *ScopedArtifacts) Delete(ctx context.Context, id string) (bool, error)

func (s *ScopedArtifacts) Exists(ctx context.Context, id string) (bool, error)

func (s *ScopedArtifacts) Get(ctx context.Context, id string) ([]byte, bool, error)

func (s *ScopedArtifacts) GetRef(ctx context.Context, id string) (*ArtifactRef, bool, error)

func (s *ScopedArtifacts) List(ctx context.Context) ([]ArtifactRef, error)

func (s *ScopedArtifacts) PutBytes(ctx context.Context, data []byte, opts PutOpts) (ArtifactRef, error)

func (s *ScopedArtifacts) PutText(ctx context.Context, text string, opts PutOpts) (ArtifactRef, error)

func (s *ScopedArtifacts) Scope() ArtifactScope