epic-12: after epic audit and init commit

2026-05-16 11:42:00 +04:00
commit c77277af0b
461 changed files with 28958 additions and 0 deletions
@@ -0,0 +1,521 @@
+---
+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.