182 lines
5.4 KiB
Markdown
182 lines
5.4 KiB
Markdown
# 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.
|