epic-12: after epic audit and init commit
This commit is contained in:
@@ -0,0 +1,489 @@
|
||||
---
|
||||
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
Block a user