= core-artifacts-store

== purpose

Defines the interface for binary blob storage of artifact payloads. Provides content-addressable put/get semantics and a flush-before-commit pattern for transactional consistency. It is the storage backend for artifact content, separate from artifact lifecycle metadata.

== responsibilities

* Storing binary artifact payloads with content-addressable IDs
* Retrieving binary artifact payloads by ID
* Supporting a transactional flush pattern: `flushBefore(commit)` ensures writes are durable before the commit action executes

== non-responsibilities

* Does not manage artifact lifecycle or metadata — those are owned by `:core:artifacts`
* Does not validate artifact payloads — validation is handled by `:core:validation`
* Does not implement the storage — this is an interface; implementations live in `:infrastructure:*`
* Does not track artifact provenance, lineage, or relationships

== key types

=== ArtifactStore
* **kind**: interface
* **purpose**: Binary blob storage for artifact payloads.
* **fields**: none
* **methods**: `put(bytes): ArtifactId`, `get(id): ByteArray?`, `flushBefore(commit)`

== event flow

This module does not interact with events. It is a pure storage interface with no event-sourced state.

== integration points

* `:core:events` — `ArtifactId` (used as the content-addressed key)

== invariants

* `ArtifactStore.put()` returns the same `ArtifactId` for the same bytes (content-addressable)
* `ArtifactStore.flushBefore(commit)` guarantees that all prior `put()` calls are durable before `commit` executes
* No event is emitted for storage operations — storage is a pure side-effect layer

== PlantUML diagram

[plantuml, core-artifacts-store, "png"]
----
include::../../diagrams/core-artifacts-store.puml[]
----




== known issues

* Only one source file exists (`ArtifactStore.kt`). There are no implementations, no default behaviour, and no in-memory fallback.

== open questions

* Should there be a default in-memory implementation for testing?
* Is `flushBefore(commit)` sufficient for all transactional patterns, or is a full begin/commit/rollback API needed?
* The module name `artifacts-store` uses a different package (`com.correx.core.artifactstore`) without the plural `artifacts`. This is inconsistent with the module name.
