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

490 lines
7.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.
Reference in New Issue View Git Blame Copy Permalink