---
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.
