8.0 KiB
name, description, depth, links
| name | description | depth | links | ||||
|---|---|---|---|---|---|---|---|
| Core Module Spec | Overall :core module responsibilities and boundaries | 2 |
|
: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
: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:
- routing validation passes
- schema validation passes
- semantic validation passes
- 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.