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