522 lines
8.0 KiB
Markdown
522 lines
8.0 KiB
Markdown
---
|
|
name: "Core Module Spec"
|
|
description: "Overall :core module responsibilities and boundaries"
|
|
depth: 2
|
|
links: ["../index.md", "../architecture/overview.md", "./core-events-submodule-spec.md", "./core-sessions-submodule-spec.md"]
|
|
---
|
|
|
|
# :core module specification
|
|
|
|
version: 0.1-draft
|
|
status: foundational specification
|
|
|
|
---
|
|
|
|
# 1. purpose
|
|
|
|
`:core` is the deterministic orchestration and domain foundation of correx.
|
|
|
|
It defines:
|
|
|
|
* domain contracts
|
|
* orchestration primitives
|
|
* workflow semantics
|
|
* event ownership rules
|
|
* validation boundaries
|
|
* execution abstractions
|
|
* replay guarantees
|
|
|
|
`:core` contains the canonical execution model of the system.
|
|
|
|
It is the authoritative source of:
|
|
|
|
* workflow state semantics
|
|
* event semantics
|
|
* transition semantics
|
|
* artifact semantics
|
|
* approval semantics
|
|
|
|
`:core` MUST remain infrastructure-independent.
|
|
|
|
---
|
|
|
|
# 2. responsibilities
|
|
|
|
`:core` owns:
|
|
|
|
* orchestration contracts
|
|
* event contracts
|
|
* transition semantics
|
|
* session lifecycle semantics
|
|
* artifact contracts
|
|
* validation contracts
|
|
* context synthesis contracts
|
|
* approval semantics
|
|
* policy contracts
|
|
* tool contracts
|
|
* inference contracts
|
|
* replay semantics
|
|
* deterministic workflow behavior
|
|
|
|
`:core` defines:
|
|
|
|
* what may happen
|
|
* what is valid
|
|
* what transitions are legal
|
|
* what state means
|
|
|
|
---
|
|
|
|
# 3. non-responsibilities
|
|
|
|
`:core` MUST NOT own:
|
|
|
|
* persistence implementation
|
|
* sqlite/postgres integration
|
|
* websocket transport
|
|
* REST APIs
|
|
* shell execution
|
|
* filesystem access
|
|
* model process management
|
|
* llama.cpp integration
|
|
* provider-specific logic
|
|
* frontend/UI concerns
|
|
* CLI rendering
|
|
* telemetry exporters
|
|
|
|
`:core` defines contracts only.
|
|
|
|
Implementations belong to infrastructure modules.
|
|
|
|
---
|
|
|
|
# 4. architectural role
|
|
|
|
`:core` acts as:
|
|
|
|
* deterministic orchestration kernel
|
|
* domain model authority
|
|
* replay authority
|
|
* execution policy authority
|
|
|
|
All external systems interact with correx through contracts defined by `:core`.
|
|
|
|
---
|
|
|
|
# 5. submodules
|
|
|
|
## mandatory submodules
|
|
|
|
```text
|
|
:core:events
|
|
:core:context
|
|
:core:validation
|
|
:core:transitions
|
|
:core:orchestration
|
|
:core:artifacts
|
|
:core:sessions
|
|
:core:approvals
|
|
:core:policies
|
|
:core:tools
|
|
:core:inference
|
|
```
|
|
|
|
---
|
|
|
|
# 6. architectural principles
|
|
|
|
## 6.1 event sourcing mandatory
|
|
|
|
All state MUST be reconstructable from immutable events.
|
|
|
|
Projections are disposable derived state.
|
|
|
|
Events are the sole source of truth.
|
|
|
|
---
|
|
|
|
## 6.2 append-only semantics
|
|
|
|
The following are immutable:
|
|
|
|
* events
|
|
* artifacts
|
|
* approvals
|
|
* tool receipts
|
|
* summaries
|
|
|
|
Mutation occurs only through new events.
|
|
|
|
---
|
|
|
|
## 6.3 deterministic orchestration
|
|
|
|
`:core` MUST behave deterministically given:
|
|
|
|
* identical event stream
|
|
* identical config
|
|
* identical transition graph
|
|
|
|
Inference nondeterminism MUST remain externalized.
|
|
|
|
---
|
|
|
|
## 6.4 infrastructure independence
|
|
|
|
`:core` MUST NOT depend on:
|
|
|
|
* infrastructure modules
|
|
* interfaces modules
|
|
* apps modules
|
|
|
|
Dependency direction is strictly inward.
|
|
|
|
---
|
|
|
|
## 6.5 explicit state ownership
|
|
|
|
Every state transition MUST have:
|
|
|
|
* originating event
|
|
* causation id
|
|
* correlation id
|
|
|
|
Hidden mutable state is forbidden.
|
|
|
|
---
|
|
|
|
# 7. dependency rules
|
|
|
|
## allowed dependencies
|
|
|
|
`:core:*` modules MAY depend on:
|
|
|
|
* kotlin stdlib
|
|
* kotlinx.coroutines
|
|
* kotlinx.serialization
|
|
* other lower-level `:core:*` modules
|
|
|
|
---
|
|
|
|
## forbidden dependencies
|
|
|
|
`:core:*` modules MUST NEVER depend on:
|
|
|
|
* `:infrastructure:*`
|
|
* `:interfaces:*`
|
|
* `:apps:*`
|
|
* frontend code
|
|
* provider implementations
|
|
|
|
---
|
|
|
|
# 8. threading and concurrency model
|
|
|
|
`:core` uses structured concurrency exclusively.
|
|
|
|
Requirements:
|
|
|
|
* coroutine-based execution
|
|
* explicit cancellation propagation
|
|
* bounded execution scopes
|
|
* deterministic lifecycle ownership
|
|
|
|
Forbidden:
|
|
|
|
* global mutable state
|
|
* unmanaged thread pools
|
|
* detached background tasks
|
|
|
|
---
|
|
|
|
# 9. state model
|
|
|
|
## authoritative state
|
|
|
|
Authoritative state exists only as:
|
|
|
|
* immutable event streams
|
|
|
|
---
|
|
|
|
## derived state
|
|
|
|
Derived state exists as:
|
|
|
|
* projections
|
|
* summaries
|
|
* context packs
|
|
* metrics
|
|
|
|
Derived state MUST be rebuildable.
|
|
|
|
---
|
|
|
|
# 10. replay guarantees
|
|
|
|
`:core` MUST support:
|
|
|
|
* full replay
|
|
* replay from cursor
|
|
* inference-skipping replay
|
|
* deterministic projection rebuild
|
|
* transition tracing
|
|
|
|
Replay MUST NOT require:
|
|
|
|
* original model availability
|
|
* original tool availability
|
|
* external provider access
|
|
|
|
---
|
|
|
|
# 11. orchestration guarantees
|
|
|
|
`:core` guarantees:
|
|
|
|
* explicit workflow transitions
|
|
* bounded retries
|
|
* approval-aware execution
|
|
* validation-first progression
|
|
* deterministic transition evaluation
|
|
|
|
`:core` MUST reject:
|
|
|
|
* invalid transitions
|
|
* invalid artifacts
|
|
* policy violations
|
|
* unauthorized escalations
|
|
|
|
---
|
|
|
|
# 12. validation guarantees
|
|
|
|
No artifact may advance workflow state unless:
|
|
|
|
1. routing validation passes
|
|
2. schema validation passes
|
|
3. semantic validation passes
|
|
4. approval validation passes
|
|
|
|
Validation failures MUST emit events.
|
|
|
|
---
|
|
|
|
# 13. approval guarantees
|
|
|
|
All risky operations MUST be classified by approval tier.
|
|
|
|
Approval semantics MUST remain:
|
|
|
|
* explicit
|
|
* replayable
|
|
* auditable
|
|
* append-only
|
|
|
|
Approval bypasses MUST emit events.
|
|
|
|
---
|
|
|
|
# 14. tool guarantees
|
|
|
|
`:core` defines:
|
|
|
|
* tool contracts
|
|
* capability contracts
|
|
* receipt contracts
|
|
* isolation expectations
|
|
|
|
Tools MUST NOT mutate workflow state directly.
|
|
|
|
All side effects MUST be represented through receipts and events.
|
|
|
|
---
|
|
|
|
# 15. inference guarantees
|
|
|
|
Models are treated as:
|
|
|
|
* stateless semantic processors
|
|
|
|
Models MUST NOT own:
|
|
|
|
* memory
|
|
* permissions
|
|
* workflow state
|
|
* transition authority
|
|
|
|
Inference outputs are proposals only.
|
|
|
|
Harness validation determines legality.
|
|
|
|
---
|
|
|
|
# 16. context guarantees
|
|
|
|
Raw context accumulation is forbidden.
|
|
|
|
All context MUST be:
|
|
|
|
* filtered
|
|
* deduplicated
|
|
* compressed
|
|
* relevance-ranked
|
|
* token-budgeted
|
|
|
|
Context packs are ephemeral synthesized views.
|
|
|
|
---
|
|
|
|
# 17. observability requirements
|
|
|
|
`:core` MUST expose structured observability hooks for:
|
|
|
|
* event tracing
|
|
* transition tracing
|
|
* replay diagnostics
|
|
* token accounting
|
|
* stage timing
|
|
* approval history
|
|
* artifact lineage
|
|
|
|
---
|
|
|
|
# 18. security boundaries
|
|
|
|
`:core` defines trust boundaries for:
|
|
|
|
* models
|
|
* tools
|
|
* providers
|
|
* plugins
|
|
* user steering
|
|
* remote execution
|
|
|
|
`:core` assumes:
|
|
|
|
* models may hallucinate
|
|
* tools may fail
|
|
* providers may become unavailable
|
|
* plugins may be untrusted
|
|
|
|
Validation and approvals are mandatory security boundaries.
|
|
|
|
---
|
|
|
|
# 19. extension model
|
|
|
|
`:core` MUST support extension through contracts/interfaces only.
|
|
|
|
Extension points include:
|
|
|
|
* validators
|
|
* compressors
|
|
* providers
|
|
* tools
|
|
* transition conditions
|
|
* policies
|
|
|
|
Extensions MUST NOT bypass:
|
|
|
|
* validation pipeline
|
|
* approval system
|
|
* event sourcing
|
|
|
|
---
|
|
|
|
# 20. persistence expectations
|
|
|
|
`:core` defines persistence contracts but not implementations.
|
|
|
|
Persistence layer MUST support:
|
|
|
|
* append-only event storage
|
|
* snapshot storage
|
|
* projection rebuild
|
|
* artifact storage
|
|
* approval audit history
|
|
|
|
---
|
|
|
|
# 21. lifecycle expectations
|
|
|
|
All runtime components MUST have explicit lifecycle ownership.
|
|
|
|
Required lifecycle semantics:
|
|
|
|
* initialization
|
|
* active execution
|
|
* cancellation
|
|
* teardown
|
|
* recovery
|
|
|
|
Zombie execution is forbidden.
|
|
|
|
---
|
|
|
|
# 22. failure semantics
|
|
|
|
Failures MUST be explicit and evented.
|
|
|
|
No silent recovery allowed.
|
|
|
|
Required failure categories:
|
|
|
|
* validation failure
|
|
* transition failure
|
|
* inference failure
|
|
* tool failure
|
|
* policy failure
|
|
* provider failure
|
|
* replay failure
|
|
|
|
All failures MUST emit structured events.
|
|
|
|
---
|
|
|
|
# 23. plugin boundaries
|
|
|
|
Plugins interact with correx only through:
|
|
|
|
* stable contracts
|
|
* DTOs
|
|
* extension interfaces
|
|
|
|
Plugins MUST NOT:
|
|
|
|
* mutate internal state directly
|
|
* bypass orchestration
|
|
* access projections unsafely
|
|
|
|
---
|
|
|
|
# 24. anti-goals
|
|
|
|
`:core` intentionally avoids:
|
|
|
|
* hidden memory
|
|
* implicit orchestration
|
|
* unrestricted autonomy
|
|
* mutable projections
|
|
* provider-specific logic
|
|
* agent personalities
|
|
* recursive uncontrolled execution
|
|
* conversationally-driven state mutation
|
|
|
|
---
|
|
|
|
# 25. philosophy summary
|
|
|
|
`:core` exists to provide deterministic orchestration around probabilistic cognition.
|
|
|
|
Reliability emerges from:
|
|
|
|
* event sourcing
|
|
* validation
|
|
* replayability
|
|
* constrained execution
|
|
* explicit approvals
|
|
* synthesized context
|
|
|
|
not from trusting model reasoning itself.
|