# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

`artifact-store` is a generic artifact registry and storage gateway for durable
generated outputs, evidence packages, reports, logs, snapshots, exports, and
release artifacts.

---

## Core Idea

Generated artifacts become valuable when they are findable, attributable,
retained for the right amount of time, and safely discardable when they expire.
This repository makes artifact preservation a shared platform concern: producers
register packages and files, the registry owns metadata and lifecycle, and
storage backends own bytes.

---

## In Scope

- Artifact package and artifact file metadata.
- Content hashing, manifests, provenance, and audit events.
- Pluggable storage backend interface with local filesystem and S3-compatible
  backends as the first targets.
- Retention classes, expiry calculation, retention extension, and holds.
- Retrieval metadata and download/link surfaces for automation.
- Pilot ingestion flow for guide-board / OpenCMIS TCK assessment output.

---

## Out of Scope

- Replacing StateHub as the work, repository, or decision system of record.
- Encoding guide-board-specific assessment semantics in the registry core.
- Formal compliance certification or legal-record guarantees by itself.
- Cloud-provider-specific lifecycle automation beyond backend adapter hooks.
- User-facing UI beyond API contracts and minimal operator documentation.

---

## Relevant When

- A tool has generated files that need durable storage and stable identifiers.
- StateHub, release records, or operators need to link to preserved evidence.
- A producer needs backend-neutral storage across local disk, Ceph RGW, or other
  S3-compatible object storage.
- Retention, hold, or deletion eligibility needs to be explicit and auditable.

---

## Not Relevant When

- The artifact is purely temporary scratch output with no retention need.
- The work is about StateHub tasks, decisions, or repository catalog data rather
  than artifact bytes and metadata.
- A producer needs domain-specific scoring, validation, or assessment semantics.
- The requirement is a human-facing artifact browser rather than API-first
  preservation.

---

## Current State

- Status: concept / service-baseline planning
- Implementation: documentation and initial workplan only
- Stability: evolving
- Usage: none yet; first pilot target is guide-board assessment output

---

## How It Fits

- Upstream dependencies: producer repositories such as `guide-board` and
  `open-cmis-tck`; future storage backends such as local filesystem and Ceph RGW.
- Downstream consumers: StateHub records, release/evidence workflows, operators,
  and future artifact search or retrieval UIs.
- Often used with: `guide-board`, `open-cmis-tck`, `kontextual-engine`,
  StateHub, and S3-compatible object storage.

---

## Terminology

- Preferred terms: artifact package, artifact file, registry record, storage
  backend, storage location, retention class, retention rule, hold.
- Also known as: artifact registry, evidence store, storage gateway.
- Potentially confusing terms: StateHub links to artifact identifiers but does
  not store artifact bytes.

---

## Related / Overlapping

- `guide-board` - produces assessment packages and evidence output.
- `open-cmis-tck` - contributes CMIS-specific assessment artifacts for the pilot.
- `kontextual-engine` - first likely subject of preserved guide-board evidence.
- `the-custodian/state-hub` - records work, decisions, repository state, and
  links to artifact registry identifiers.

---

## Getting Oriented

- Start with: `INTENT.md`.
- Key files / directories: `docs/ARCHITECTURE-BLUEPRINT.md`, `workplans/`.
- Entry points: no service entry point yet; see
  `workplans/ARTIFACT-STORE-WP-0001-service-baseline.md`.

---

## Provided Capabilities

```capability
type: infrastructure
title: Artifact package preservation
description: Register generated artifact packages and files, store bytes through a configured backend, compute hashes, apply retention policy, and return stable package identifiers for StateHub or producer records.
keywords: [artifacts, evidence, retention, storage, registry, provenance]
```

---

## Notes

The first concrete pilot is preserving `guide-board` / `open-cmis-tck`
assessment output for `kontextual-engine`.