---
name: "Core Artifacts Submodule Spec"
description: "Specification for :core:artifacts – structured outputs with lineage"
depth: 2
links: ["../index.md", "./core-module-spec.md", "./core-context-submodule-spec.md"]
---

# :core:artifacts module specification

version: 0.1-draft
status: foundational specification

---

# 1. purpose

`:core:artifacts` defines the canonical structured output model for correx.

It is the authoritative subsystem for:

* artifact contracts
* artifact lifecycle semantics
* schema ownership
* lineage tracking
* artifact immutability
* artifact validation boundaries
* artifact serialization contracts

Artifacts represent:

* structured outputs produced during orchestration
* machine-validated workflow state contributions
* replayable execution products

Artifacts are the primary mechanism through which models contribute semantic work to the harness.

---

# 2. responsibilities

`:core:artifacts` owns:

* base artifact contracts
* artifact schema contracts
* artifact lifecycle semantics
* lineage semantics
* artifact identity semantics
* immutability guarantees
* serialization contracts
* artifact metadata contracts
* artifact relationship semantics
* artifact provenance semantics

---

# 3. non-responsibilities

`:core:artifacts` MUST NOT own:

* artifact persistence implementations
* semantic validation logic
* transition evaluation
* orchestration progression
* model execution
* tool execution
* UI rendering
* websocket serialization transport

Artifact legality is validated externally.

---

# 4. architectural role

`:core:artifacts` acts as:

* structured semantic output authority
* workflow data contract authority
* lineage authority
* execution provenance authority

All meaningful workflow progression MUST operate on artifacts rather than freeform model text.

---

# 5. design principles

## 5.1 artifacts are immutable

Artifacts MUST NEVER be mutated after creation.

Corrections MUST produce:

* new artifacts
* superseding relationships
* compensating events

---

## 5.2 artifacts are structured

Artifacts MUST conform to explicit schemas.

Freeform orchestration state is forbidden.

---

## 5.3 artifacts are replayable

Artifacts MUST remain:

* serializable
* deterministic
* reconstructable
* versioned

Replay MUST reproduce identical artifact history.

---

## 5.4 artifacts are proposals

Artifacts represent proposed semantic state.

Artifacts gain workflow authority only after:

* validation
* approvals
* transition acceptance

---

# 6. artifact model

## base artifact contract

```kotlin id="zskldn"
sealed interface Artifact {
    val id: ArtifactId
    val sessionId: SessionId
    val stageId: StageId
    val schemaVersion: Int
    val createdAt: Instant
    val lineage: ArtifactLineage
    val metadata: ArtifactMetadata
}
```

---

# 7. artifact identity semantics

Artifact identifiers MUST be:

* globally unique
* immutable
* replay-stable

Artifact identity MUST NOT depend on:

* provider internals
* runtime memory
* mutable projections

---

# 8. artifact lifecycle model

Mandatory lifecycle phases:

```text id="oztzsu"
CREATED
VALIDATING
VALIDATED
REJECTED
SUPERSEDED
ARCHIVED
```

Lifecycle changes MUST emit events.

---

# 9. schema model

Artifacts MUST conform to explicit schemas.

Schemas MAY be:

* built-in
* config-defined
* plugin-defined

Recommended schema model:

* kotlinx.serialization
* pydantic-compatible external definitions
* explicit versioning

---

## schema guarantees

Schemas MUST support:

* deterministic validation
* version compatibility
* explicit field typing
* replay-safe deserialization

---

# 10. artifact lineage model

All artifacts MUST support lineage tracking.

Lineage MUST include:

* parent artifacts
* originating events
* originating stage
* tool receipts
* validation history
* approval history

---

## lineage guarantees

Lineage MUST remain:

* immutable
* replayable
* traceable

---

# 11. provenance model

Artifacts MUST record provenance metadata for:

* originating model
* provider
* stage runtime
* generation config
* tool interactions
* context pack references

This metadata exists for:

* replay
* diagnostics
* auditability
* evaluation

---

# 12. artifact relationships

Supported relationships:

```text id="1wz8ny"
PARENT
CHILD
SUPERSEDES
DERIVED_FROM
VALIDATED_BY
APPROVED_BY
GENERATED_FROM
```

Relationships MUST remain append-only.

---

# 13. serialization requirements

Artifacts MUST support:

* deterministic serialization
* schema versioning
* replay-safe decoding
* portable encoding

Recommended:

* kotlinx.serialization

Forbidden:

* provider-specific formats
* reflection-dependent serialization
* mutable serialization contracts

---

# 14. validation boundaries

`:core:artifacts` defines structure only.

Validation responsibilities belong to:

* `:core:validation`
* `:core:approvals`
* `:core:policies`

Artifacts themselves MUST remain validation-agnostic.

---

# 15. artifact categories

Recommended top-level categories:

```text id="k93gb0"
ReasoningArtifact
PatchArtifact
PlanArtifact
SummaryArtifact
CommandArtifact
AnalysisArtifact
ToolResultArtifact
ContextArtifact
ApprovalArtifact
RecoveryArtifact
```

Additional categories MAY be plugin-defined.

---

# 16. artifact storage expectations

Artifacts MUST remain:

* append-only
* immutable
* replay-safe

Storage implementations belong to infrastructure modules.

---

# 17. replay guarantees

Replay MUST reconstruct:

* artifact history
* artifact lineage
* artifact relationships
* supersession chains
* validation history

Replay MUST NOT require:

* original models
* provider access
* live tool execution

---

# 18. supersession semantics

Corrections MUST occur through:

* replacement artifacts
* supersession relationships

Historical artifacts MUST remain preserved.

Example:

```text id="vgzfh7"
Artifact B
  SUPERSEDES
Artifact A
```

Mutation-in-place is forbidden.

---

# 19. observability requirements

`:core:artifacts` MUST expose metadata hooks for:

* lineage tracing
* artifact provenance
* supersession chains
* validation outcomes
* approval history
* schema evolution
* replay diagnostics

---

# 20. security boundaries

Artifacts are considered:

* untrusted semantic proposals

Artifacts MUST NOT gain execution authority directly.

Execution authority requires:

* validation
* policy approval
* orchestration approval

Sensitive payload handling MUST support:

* redaction
* isolation
* audit-safe serialization

---

# 21. extension model

Extensions MAY define:

* custom schemas
* custom artifact categories
* custom metadata
* custom lineage relationships

Extensions MUST NOT:

* mutate historical artifacts
* bypass validation
* bypass replay guarantees
* introduce hidden mutable state

---

# 22. forbidden patterns

Forbidden:

* mutable artifacts
* freeform orchestration state
* schema-less execution artifacts
* artifact-owned workflow state
* hidden lineage mutation
* in-place correction
* replay-dependent artifact interpretation

---

# 23. persistence expectations

Persistence implementations MUST support:

* immutable storage
* lineage reconstruction
* version-safe retrieval
* replay-safe deserialization

Persistence belongs to infrastructure modules.

---

# 24. testing requirements

`:core:artifacts` MUST support deterministic testing for:

* schema validation
* serialization consistency
* lineage reconstruction
* supersession handling
* replay reconstruction
* version compatibility

---

# 25. philosophy summary

`:core:artifacts` exists to transform probabilistic model outputs into structured replayable workflow objects.

Reliability emerges from:

* immutable schemas
* explicit lineage
* deterministic serialization
* append-only history
* validation boundaries

not from trusting raw model text directly.