correx/docs/epics/epic-6-resolution.md

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):

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:

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:

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

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.