epic-12: after epic audit and init commit

2026-05-16 11:42:00 +04:00
commit c77277af0b
461 changed files with 28958 additions and 0 deletions
@@ -0,0 +1,181 @@
+# 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.