kami/correx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8b6eedcf871bbf2c7d62047ac59bd5f0b83ffeaf
correx/docs/modules/core-artifacts-submodule-spec.md
T

7.6 KiB
Raw Blame History

name, description, depth, links
name description depth links
Core Artifacts Submodule Spec Specification for :core:artifacts – structured outputs with lineage 2
../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

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:

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:

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:

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:

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.

Reference in New Issue View Git Blame Copy Permalink