epic-12: after epic audit and init commit
This commit is contained in:
@@ -0,0 +1,88 @@
|
||||
---
|
||||
name: "Context Layers"
|
||||
description: "Context hierarchy, compression, and token budgeting"
|
||||
depth: 2
|
||||
links:
|
||||
- "../index.md"
|
||||
- "./overview.md"
|
||||
- "./replay-model.md"
|
||||
---
|
||||
|
||||
# context layers
|
||||
|
||||
**version:** 0.1-draft
|
||||
**status:** architectural reference
|
||||
|
||||
---
|
||||
|
||||
## 1. motivation
|
||||
|
||||
Raw conversation accumulation destroys performance in local models. Correx forces all context to be synthesized, filtered, and layer‑separated before it reaches a model.
|
||||
|
||||
---
|
||||
|
||||
## 2. layer model
|
||||
|
||||
```
|
||||
L0 live execution [active request, current tool output, pending approval text]
|
||||
L1 stage‑local context [artifacts and receipts from the current stage]
|
||||
L2 compressed session [summaries of completed stages; kept under a token cap]
|
||||
L3 project memory [persistent facts, architecture decisions, key outputs]
|
||||
L4 archival history [full event log; not used for inference]
|
||||
```
|
||||
|
||||
Models receive a ContextPack built from L0–L2, with L3 optionally injected if relevant.
|
||||
|
||||
---
|
||||
|
||||
## 3. context pack building pipeline
|
||||
|
||||
1. **Retrieve** – pull relevant events from projections using the current session cursor.
|
||||
2. **Deduplicate** – remove duplicate artifact versions, identical tool receipts, and stale retries. (Tool output deduplication happens later, within the tool‑specific compressor.)
|
||||
3. **Rank** – order entries by recency and relevance to the current stage’s declared goal (simple heuristic, no model required).
|
||||
4. **Compress (layer‑specific, deterministic):**
|
||||
* **Tool logs** → RTK‑style pipeline: filter noise → group similar items → deduplicate repeated lines → truncate to token budget; **full output always saved on failure** and replaced with a file pointer. Per‑tool regex patterns from the tool definition control what’s extracted.
|
||||
* **Conversation** → keep last N messages verbatim; **manually triggered compaction** (`/compact`) summarizes older turns; **micro‑compaction** silently clears old tool outputs when token pressure rises; pinned messages survive compaction. No automatic summarization.
|
||||
* **Artifacts** → chunkable artifacts (e.g., plans) split into steps; only current step ±1 remains in context, rest stored on disk. Non‑chunkable artifacts use their mandatory `summary` field directly.
|
||||
* **Steering notes** → kept verbatim.
|
||||
* **Event history → L2** → **harvest structured DecisionPoints** from completed stages: artifact `summary` + `rationale` + approval steering + stage outcome. No summarization model; pure field extraction.
|
||||
5. **Inject policies** – attach active permissions, allowed tools, and stage‑specific rules.
|
||||
6. **Tokenize & trim** – enforce hard token budget; if exceeded, oldest L2 DecisionPoints are dropped first (they graduate to L3 project memory).
|
||||
7. **Assemble** – produce the final, deterministic **ContextPack**.
|
||||
|
||||
This pipeline is entirely rule‑based, replay‑safe, and uses zero model calls for compression.
|
||||
|
||||
---
|
||||
|
||||
## 4. context pack structure
|
||||
|
||||
```kotlin
|
||||
data class ContextPack(
|
||||
val layers: Map<ContextLayer, List<ContextEntry>>,
|
||||
val budgetUsed: Int,
|
||||
val budgetLimit: Int
|
||||
)
|
||||
```
|
||||
|
||||
Each entry is a typed reference to an event, artifact excerpt, summary, or policy snippet.
|
||||
|
||||
---
|
||||
|
||||
## 5. router context isolation
|
||||
|
||||
The Router maintains its own separate L2 memory, rebuilt from stage summaries. During active execution, the Router’s context is unloaded from the execution model’s context window. When the user interrupts, the Router rebuilds its view from the latest L2 snapshot, interprets steering, and injects it without polluting the execution model.
|
||||
|
||||
---
|
||||
|
||||
## 6. token budgeting
|
||||
|
||||
* Each model and stage can define a max token limit.
|
||||
* System prompts and policies reserve a portion.
|
||||
* If the compressed context still exceeds the budget, older L2 entries are merged into L3 and dropped from L2.
|
||||
* A session‑level cap on L2 memory exists to prevent gradual bloat in long‑running sessions.
|
||||
|
||||
---
|
||||
|
||||
## 7. observability
|
||||
|
||||
The context processor emits events (`ContextPackBuilt`, `LayerTruncated`) with metrics on compression ratios, token usage, and deduplication hits. This data is invaluable for tuning compression strategies.
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
name: "Event Model"
|
||||
description: "Canonical event structure, categories, and causality"
|
||||
depth: 2
|
||||
links:
|
||||
- "../index.md"
|
||||
- "./overview.md"
|
||||
- "./replay-model.md"
|
||||
---
|
||||
|
||||
# event model
|
||||
|
||||
**version:** 0.1-draft
|
||||
**status:** architectural reference
|
||||
|
||||
---
|
||||
|
||||
## 1. purpose
|
||||
|
||||
Events are the sole source of truth for all workflow state in correx. Every meaningful action (user input, stage start, artifact produced, approval granted, transition executed) is recorded as an immutable event.
|
||||
|
||||
---
|
||||
|
||||
## 2. event structure
|
||||
|
||||
Every event contains:
|
||||
|
||||
```kotlin
|
||||
sealed interface Event {
|
||||
val id: EventId
|
||||
val sessionId: SessionId
|
||||
val timestamp: Instant
|
||||
val type: EventType
|
||||
val payload: EventPayload
|
||||
val causationId: EventId? // what directly caused this event?
|
||||
val correlationId: CorrelationId? // which workflow/execution lineage?
|
||||
val sequence: Long // strict append order within session
|
||||
val version: Int // schema version
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. event categories
|
||||
|
||||
| category | owner module | examples |
|
||||
|----------|--------------|----------|
|
||||
| DomainEvents | core:events, core:artifacts | ArtifactProduced, ArtifactSuperseded |
|
||||
| LifecycleEvents | core:sessions | SessionCreated, SessionCompleted |
|
||||
| InferenceEvents | core:inference | InferenceStarted, InferenceCompleted |
|
||||
| ToolEvents | core:tools | ToolInvocationRequested, ToolExecutionCompleted |
|
||||
| ValidationEvents | core:validation | ArtifactValidated, ArtifactRejected |
|
||||
| ApprovalEvents | core:approvals | ApprovalRequested, ApprovalGranted |
|
||||
| CompressionEvents | core:context | ContextPackBuilt, CompressionApplied |
|
||||
| TransitionEvents | core:transitions | TransitionExecuted, StageScheduled |
|
||||
| ProjectionEvents | core:events | ProjectionRebuilt |
|
||||
| SystemEvents | various | WatchdogTimeout, ProviderHealthChanged |
|
||||
|
||||
---
|
||||
|
||||
## 4. causal chain (simplified)
|
||||
|
||||
```
|
||||
UserInputReceived
|
||||
└→ SessionCreated
|
||||
└→ StageScheduled
|
||||
└→ ContextPackBuilt
|
||||
└→ InferenceStarted
|
||||
└→ ArtifactProduced
|
||||
└→ ArtifactValidated
|
||||
├→ (if approval needed) ApprovalRequested → ApprovalGranted
|
||||
└→ TransitionExecuted
|
||||
└→ (next stage)
|
||||
```
|
||||
|
||||
Causation IDs form an explicit directed acyclic graph; every event can be traced back to its origin.
|
||||
|
||||
---
|
||||
|
||||
## 5. ordering and append guarantees
|
||||
|
||||
* Events are append‑only. Existing events are never modified or deleted.
|
||||
* Sequence numbers are strictly increasing within a session, gap‑free.
|
||||
* Compensating events (e.g., `ArtifactSuperseded`) are themselves new events; they do not alter history.
|
||||
* Ordering during replay must exactly match the original insertion order.
|
||||
|
||||
---
|
||||
|
||||
## 6. replay semantics
|
||||
|
||||
Given a sequence of events, replay rebuilds all projections and workflow state deterministically. For inference‑skipping replay, artifacts and validation outcomes are read directly from recorded events rather than re‑invoking models.
|
||||
|
||||
---
|
||||
|
||||
## 7. snapshotting
|
||||
|
||||
Snapshots are periodically rebuilt from event streams to speed up replay. They are **disposable optimisation artifacts**; the event log remains the authority.
|
||||
|
||||
---
|
||||
|
||||
## 8. extension and versioning
|
||||
|
||||
New event types may be added by core modules or plugins. Schema evolution is handled via version numbers and migration logic that never alters historical events.
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
name: "System Overview"
|
||||
description: "System overview and core metaphor of Correx"
|
||||
depth: 2
|
||||
links:
|
||||
- "../index.md"
|
||||
- "./event-model.md"
|
||||
- "./replay-model.md"
|
||||
- "./context-layers.md"
|
||||
- "./security-boundaries.md"
|
||||
---
|
||||
|
||||
# system overview
|
||||
|
||||
**version:** 0.1-draft
|
||||
**status:** architectural narrative
|
||||
|
||||
---
|
||||
|
||||
## 1. what is correx?
|
||||
|
||||
Correx is a **local‑first orchestration runtime** for structured LLM workflows. It provides a deterministic shell around probabilistic cognition, treating language models as interchangeable execution engines while owning memory, state, validation, and permissions.
|
||||
|
||||
The system is not a chatbot framework. It is a config‑driven workflow orchestrator that treats every model output as an untrusted proposal and only advances state after multiple layers of validation and approval.
|
||||
|
||||
---
|
||||
|
||||
## 2. core metaphor
|
||||
|
||||
**Harness is the brain, models are the muscles, Router is the face.**
|
||||
|
||||
* **Harness (core kernel):** orchestrates workflow, owns lifecycle, validates everything, maintains event‑sourced state.
|
||||
* **Router:** conversational façade that chit‑chats with the user, provides summaries, and interprets steering; always available but never persists in execution context.
|
||||
* **Agents:** ephemeral, stateless workers that consume synthesized context and emit structured artifacts.
|
||||
* **Models:** stateless inference engines; they receive only a tightly compressed context pack and produce a single response.
|
||||
|
||||
---
|
||||
|
||||
## 3. key architectural properties
|
||||
|
||||
| property | implementation |
|
||||
|----------|----------------|
|
||||
| event‑sourced | all state is derivable from immutable events |
|
||||
| deterministic‑enough | orchestration logic is deterministic; inference randomness is contained |
|
||||
| replayable | full session replay without original models or live tools |
|
||||
| provider‑agnostic | local GGUF and remote OpenAI‑compatible models are interchangeable |
|
||||
| context‑efficient | aggressive compression, budgeting, and layering prevents context bloat |
|
||||
| bounded autonomy | explicit tiers, approval gates, and cancellation boundaries |
|
||||
| validation‑first | every artifact passes routing → schema → semantic → approval validation |
|
||||
|
||||
---
|
||||
|
||||
## 4. system layers
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ user │
|
||||
└───────┬─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ interfaces │ cli, api, websocket, frontend
|
||||
└───────┬─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ orchestration │ session life, stage scheduling, retry, coordination
|
||||
└───────┬─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ core domain │ events, transitions, validation, approvals, context, artifacts
|
||||
└───────┬─────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ infrastructure │ persistence, inference providers, tool runtime, sandboxing
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
Core never depends on infrastructure. Infrastructure implements contracts defined by core.
|
||||
|
||||
---
|
||||
|
||||
## 5. execution flow (simplified)
|
||||
|
||||
1. User input arrives via Router.
|
||||
2. Session is created or resumed; projection rebuilt from events.
|
||||
3. Orchestrator determines next stage (from transition graph).
|
||||
4. Context Processor synthesises a ContextPack from L0–L2 layers.
|
||||
5. Inference module selects and calls the appropriate model.
|
||||
6. Model output is parsed into an artifact.
|
||||
7. Validation pipeline checks artifact (routing, schema, semantic, approval).
|
||||
8. If approved, transition engine evaluates conditions and moves to next stage.
|
||||
9. All steps are recorded as events.
|
||||
|
||||
---
|
||||
|
||||
## 6. design philosophy
|
||||
|
||||
Correx is an **orchestration kernel** that enforces strict separation of concerns, immutability, and replayability. Reliability comes from explicit constraints, not from trusting model intelligence.
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
name: "Replay Model"
|
||||
description: "Replay modes, guarantees, and snapshot/cursor management"
|
||||
depth: 2
|
||||
links:
|
||||
- "../index.md"
|
||||
- "./overview.md"
|
||||
- "./event-model.md"
|
||||
---
|
||||
|
||||
# replay model
|
||||
|
||||
**version:** 0.1-draft
|
||||
**status:** architectural reference
|
||||
|
||||
---
|
||||
|
||||
## 1. purpose
|
||||
|
||||
Replay is the ability to reconstruct the entire state of a session (projections, context builds, validation outcomes, transitions) purely from the immutable event log. It is a mandatory architectural guarantee, not an afterthought.
|
||||
|
||||
---
|
||||
|
||||
## 2. replay modes
|
||||
|
||||
| mode | description |
|
||||
|------|-------------|
|
||||
| **full replay** | re‑apply all events, including inference (may re‑run models if available) |
|
||||
| **partial replay** | replay from a given cursor/sequence number |
|
||||
| **inference‑skipping replay** | skip model calls; use recorded `InferenceCompleted` events directly |
|
||||
| **projection‑only replay** | rebuild projections without touching orchestration |
|
||||
| **deterministic simulation** | test mode: compare current outcomes against a golden reference |
|
||||
|
||||
---
|
||||
|
||||
## 3. what can be replayed?
|
||||
|
||||
* Session lifecycle (creation → completion)
|
||||
* Stage scheduling and transitions
|
||||
* Context pack building (subject to the same compression config, but compression events may be reused)
|
||||
* Validation decisions (recorded pass/reject)
|
||||
* Approval decisions (recorded as events)
|
||||
* Tool receipts (recorded; actual tool code not re‑executed unless in simulation mode)
|
||||
* All projections
|
||||
|
||||
---
|
||||
|
||||
## 4. what is NOT needed for replay?
|
||||
|
||||
* The original model weights
|
||||
* Live tool access
|
||||
* Network connectivity
|
||||
* Provider credentials
|
||||
* The original Router UI
|
||||
|
||||
Replay is self‑contained within the event store and configuration.
|
||||
|
||||
---
|
||||
|
||||
## 5. deterministic guarantees
|
||||
|
||||
Replay is deterministic when:
|
||||
|
||||
* the event store is unchanged
|
||||
* the configuration (workflows, policies, compression rules) is identical
|
||||
* the replay strategy matches (e.g., inference‑skipping uses recorded artifacts)
|
||||
|
||||
Non‑determinism from model inference is thereby contained: the replay decision to trust a recorded artifact is itself a deterministic choice driven by the replay mode.
|
||||
|
||||
---
|
||||
|
||||
## 6. use cases
|
||||
|
||||
* **debugging:** replay a failed session step‑by‑step, inspecting context packs and validation outcomes.
|
||||
* **audit:** prove which decision led to a tool execution and why.
|
||||
* **recovery:** if the harness crashes, resume from the last stable event cursor.
|
||||
* **dataset generation:** replay workflows with different inference providers to produce synthetic training data.
|
||||
* **testing:** deterministic simulation lets you verify orchestration logic without real models.
|
||||
|
||||
---
|
||||
|
||||
## 7. snapshot and cursor management
|
||||
|
||||
To avoid replaying 100k+ events every time, the system supports periodic snapshots and replay cursors. A snapshot is a point‑in‑time projection bundle paired with the sequence number of the last applied event. Replay then only re‑processes events after that cursor.
|
||||
|
||||
---
|
||||
|
||||
## 8. implementation constraints
|
||||
|
||||
* All projections must be buildable from events alone.
|
||||
* Context pack builds must be replays (using recorded compression events when possible).
|
||||
* No component may depend on in‑memory state that is not derived from events.
|
||||
* Events must remain serializable and versioned forever.
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
name: "Security Boundaries"
|
||||
description: "Trust boundaries and component isolation rules"
|
||||
depth: 2
|
||||
links:
|
||||
- "../index.md"
|
||||
- "./overview.md"
|
||||
---
|
||||
|
||||
# security boundaries
|
||||
|
||||
**version:** 0.1-draft
|
||||
**status:** architectural reference
|
||||
|
||||
---
|
||||
|
||||
## 1. trust model
|
||||
|
||||
Correx operates under the assumption that **models are untrusted**, **tools are dangerous**, and **plugins may be malicious**. The system enforces explicit security boundaries between components to contain risk.
|
||||
|
||||
---
|
||||
|
||||
## 2. principal boundaries
|
||||
|
||||
```
|
||||
┌───────────────┐
|
||||
│ user │ human, interactive steering, ultimate authority
|
||||
└───────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────┐
|
||||
│ router │ facial facade; can only summarise, interpret, forward
|
||||
└───────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ harness (core) │
|
||||
│ orchestrator, validation, approvals, │
|
||||
│ transitions, policies, event store │
|
||||
│ │
|
||||
│ all sensitive decisions happen here │
|
||||
└───┬───────┬───────┬──────────┬──────┬───────┘
|
||||
│ │ │ │ │
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
┌─────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
|
||||
│model│ │tool │ │prov- │ │plugin│ │pers- │
|
||||
│ │ │ │ │ider │ │ │ │ist │
|
||||
└─────┘ └──────┘ └──────┘ └──────┘ └──────┘
|
||||
|
||||
Boundaries are strictly enforced:
|
||||
- Model ⇄ Harness: only text in, artifact out
|
||||
- Tool ⇄ Harness: only receipts, no direct state mutation
|
||||
- Provider ⇄ Harness: only inference interface
|
||||
- Plugin ⇄ Harness: only via published contracts
|
||||
- Persistence ⇄ Harness: only through storage interfaces
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. specific boundary rules
|
||||
|
||||
### 3.1 model boundary
|
||||
|
||||
* Models receive only ContextPacks; they never access raw events, files, or network.
|
||||
* Output is untrusted; validation pipeline scrutinises every artifact.
|
||||
* No state carried between model calls.
|
||||
|
||||
### 3.2 tool boundary
|
||||
|
||||
* All tools are assigned an approval tier (T0–T4).
|
||||
* Execution requires explicit approval matching the tier and session mode.
|
||||
* Tools run sandboxed (containerised or restricted shell).
|
||||
* Tools may only affect the filesystem paths allowed by policies.
|
||||
* Network access is blocked by default; curl, etc., require tier T3 and explicit approval.
|
||||
|
||||
### 3.3 provider boundary
|
||||
|
||||
* Local and remote providers are abstracted behind the same `InferenceProvider` interface.
|
||||
* Credentials are never exposed to core logic; they reside in environment variables or secret vaults.
|
||||
* Provider health failures trigger orchestration fallback, not panic.
|
||||
|
||||
### 3.4 plugin boundary
|
||||
|
||||
* Plugins (custom validators, compressors, tools) interact via stable DTOs.
|
||||
* They cannot mutate core projections or approval decisions.
|
||||
* Plugin code is loaded into an isolated classloader/process in later versions.
|
||||
|
||||
### 3.5 user boundary
|
||||
|
||||
* User interaction happens only through the Router and approval prompts.
|
||||
* Steering input is recorded verbatim and later injected as guidance into context packs.
|
||||
* Session cancellation is immediate and enforced by the orchestrator.
|
||||
|
||||
---
|
||||
|
||||
## 4. extra safeguards
|
||||
|
||||
* **Audit trail:** every approval, validation rejection, and tool execution is permanently recorded.
|
||||
* **Least privilege:** each component starts with zero access and gains only what is explicitly granted.
|
||||
* **Execution timeouts:** all inference and tool calls have strict durations; watchdog kills overruns.
|
||||
* **Secrets isolation:** no secret appears in logs, events, or context unless explicitly allowed.
|
||||
* **Replay safety:** replay does not re‑execute risky side effects; it only reconstructs state.
|
||||
|
||||
---
|
||||
|
||||
## 5. what we do not protect against (by design)
|
||||
|
||||
* Deliberate user bypasses (e.g., yolo mode) – they are logged but allowed.
|
||||
* Model‑generated harmful content – semantic validation can flag it, but ultimate responsibility lies with the user’s policies.
|
||||
* Physical machine compromise – we assume the OS and sandbox provide the last line of defence.
|
||||
Reference in New Issue
Block a user