# Epic 6 — Artifact System (Contract Layer + Lifecycle Events)

## completed deliverables

### 1. artifact identity

introduced `ArtifactId` as a type alias to `TypeId` in `core:events`, following the established identity type pattern.

* lives in `core:events` alongside `SessionId`, `StageId`, and other shared vocabulary types
* available to all modules that depend on `:core:events`
* no circular dependency risk

---

### 2. artifact lifecycle phase model

introduced `ArtifactLifecyclePhase` as a serializable enum in `core:events`.

phases (in mandatory transition order):

```text
CREATED → VALIDATING → VALIDATED → REJECTED
                   ↘ SUPERSEDED → ARCHIVED
```

properties:

* all six phases are mandatory by spec
* lives in `core:events` so lifecycle events can reference it with full type safety
* corrections to artifacts produce new artifacts via supersession — not in-place edits

---

### 3. artifact contract layer

introduced the `Artifact` sealed interface as the root domain abstraction for all structured model outputs.

final structure:

```text
Artifact (sealed interface)
 ├── id (ArtifactId)
 ├── sessionId (SessionId)
 ├── stageId (StageId)
 ├── schemaVersion (Int)
 ├── createdAt (Instant)
 ├── lifecyclePhase (ArtifactLifecyclePhase)
 ├── lineage (ArtifactLineage)
 └── metadata (Map<String, String>)
```

properties:

* immutable after creation
* serialization-safe via kotlinx.serialization
* no infrastructure coupling
* extensible — concrete artifact categories are deferred

---

### 4. artifact relationship model

introduced append-only relationship tracking between artifacts.

final structures:

* `ArtifactRelationshipType` — seven typed relationships:
    * `PARENT`, `CHILD`, `SUPERSEDES`, `DERIVED_FROM`
    * `VALIDATED_BY`, `APPROVED_BY`, `GENERATED_FROM`
* `ArtifactRelationship(sourceId, targetId, type)`

properties:

* relationships are append-only — never mutated or removed
* all relationship changes produce new events

---

### 5. artifact lineage model

introduced immutable lineage tracking for all artifacts.

final structure:

```text
ArtifactLineage
 ├── parentIds (List<ArtifactId>)
 ├── relationships (List<ArtifactRelationship>)
 └── validationResultIds (List<String>)
```

properties:

* fully serializable
* validation results referenced by ID only — no direct dependency on `core:validation`
* replayable and traceable from event log alone

---

### 6. artifact serialization module

introduced `artifactModule: SerializersModule` in `core:artifacts`.

* polymorphic block scaffolded for concrete artifact subclasses (deferred)
* follows the same pattern as `eventModule` in `core:events`

---

### 7. artifact lifecycle events

introduced seven lifecycle events in `core:events`, covering the full artifact lifecycle and relationship tracking.

events:

* `ArtifactCreatedEvent(artifactId, sessionId, stageId, schemaVersion)`
* `ArtifactValidatingEvent(artifactId, sessionId, stageId)`
* `ArtifactValidatedEvent(artifactId, sessionId, stageId)`
* `ArtifactRejectedEvent(artifactId, sessionId, stageId, reason)`
* `ArtifactSupersededEvent(artifactId, supersededById, sessionId, stageId)`
* `ArtifactArchivedEvent(artifactId, sessionId, stageId)`
* `ArtifactRelationshipAddedEvent(sourceId, targetId, relationshipType, sessionId)`

properties:

* all registered in `eventModule` polymorphic block
* `relationshipType` carried as `String` to avoid circular dependency with `core:artifacts`
* serialization-safe, replay-ready

---

# final architecture after Epic 6

```text
Artifact (sealed interface — root abstraction)
    ↓
ArtifactLifecyclePhase (CREATED → ... → ARCHIVED)
    ↓
ArtifactLineage (parentIds + relationships + validationResultIds)
    ↓
ArtifactRelationship (append-only, 7 typed relationships)
    ↓
Lifecycle events in core:events (7 events, all registered)
    ↓
artifactModule (SerializersModule, ready for subclass registration)
```

---

# major architectural outcomes

Epic 6 established:

* type-safe artifact identity integrated into the shared event vocabulary
* immutable, replayable artifact contract with full lifecycle phase tracking
* append-only relationship graph with seven typed relationship kinds
* lineage model decoupled from validation internals (reference by ID only)
* lifecycle event backbone enabling state reconstruction from events alone
* serialization module scaffolded for concrete artifact categories

---

# what Epic 6 intentionally does NOT include

not implemented:

* concrete artifact categories (`ReasoningArtifact`, `PatchArtifact`, `PlanArtifact`, etc.)
* artifact reducer, projector, or repository (state reconstruction layer)
* persistence — artifacts are not stored independently; state rebuilds from events
* provenance metadata model (originating model, provider, generation config, tool receipts)
* semantic validation — artifact legality is validated externally by `:core:validation`
* approval integration

those are explicitly deferred to later epics.

---

# final state

Correx now has:

> an immutable, event-sourced artifact contract layer with typed identity, a mandatory six-phase lifecycle, append-only relationship tracking, and a full suite of lifecycle events — establishing the structured output abstraction through which models contribute semantic work to the system, with state fully reconstructable from the event log.