docs(dox): build out the DOX AGENTS.md hierarchy
Root Child DOX Index assembled, plus a per-module AGENTS.md across the tree (core/*, infrastructure/*, apps/*, testing/*, and docs/examples/frontend/etc), each following the DOX section shape: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index.
This commit is contained in:
@@ -0,0 +1,39 @@
|
||||
# infrastructure/
|
||||
|
||||
## Purpose
|
||||
|
||||
Real-world adapters for the correx kernel. Each submodule wires a concrete external system (SQLite, llama.cpp server, TurboVec sidecar, OS shell, SearXNG/web) to the interfaces declared in `core:*`. The root module (`infrastructure/`) contains `InfrastructureModule` — a single factory object that assembles and wires all adapters for use by `apps/*`.
|
||||
|
||||
## Ownership
|
||||
|
||||
Adapter layer. Depends on `core:*`. No upward dependency on `apps/*` is permitted.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- All adapters implement interfaces declared in `core:*` — never invent adapter-specific abstractions visible outside this layer.
|
||||
- `InfrastructureModule` is the sole DI assembly point: `apps/*` call its factory functions; they do not instantiate adapters directly.
|
||||
- Tool side effects must be captured in events (invariant #5). Adapters must not execute tool side effects silently.
|
||||
- Environment observations (filesystem state, network responses, embedder results) must be recorded as events at call time; replay must not re-query the environment (invariants #8, #9).
|
||||
- No cross-core imports. Adapters may depend on multiple `core:*` modules but never on sibling `infrastructure:*` modules except through `InfrastructureModule` wiring.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Kotlin error handling: use `runCatching` / sealed domain types; no bare `try-catch`.
|
||||
- Blocking I/O goes in `withContext(Dispatchers.IO)`.
|
||||
- Imports: verify each is used before finalising a file; remove unused imports.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :infrastructure:test --rerun-tasks
|
||||
./gradlew check
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
- [artifacts-cas/](artifacts-cas/AGENTS.md) — content-addressable artifact store backed by SQLite index + append-only segment files
|
||||
- [inference/](inference/AGENTS.md) — inference provider registry and llama.cpp adapter (model lifecycle, embedder, tokenizer)
|
||||
- [persistence/](persistence/AGENTS.md) — SQLite event store and in-memory event store; artifact repository projection
|
||||
- [router/](router/AGENTS.md) — L3 memory adapter (TurboVec Python sidecar) for cross-session router memory
|
||||
- [tools/](tools/AGENTS.md) — tool registry, sandboxed executor, shell/web/task/filesystem tool implementations
|
||||
- [workflow/](workflow/AGENTS.md) — TOML workflow loader, prompt loader, execution plan compiler
|
||||
@@ -0,0 +1,33 @@
|
||||
# infrastructure/artifacts-cas/
|
||||
|
||||
## Purpose
|
||||
|
||||
Content-addressable artifact store backed by append-only segment files on disk and a SQLite index. Implements `core:artifacts-store` (`ArtifactStore`). Handles content hashing, segment layout, compaction, eviction, and crash-recovery tail scanning.
|
||||
|
||||
## Ownership
|
||||
|
||||
Adapter for local filesystem artifact storage. No dependency on other `infrastructure:*` modules at runtime; `infrastructure:persistence` is a test dependency only.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Implements `ArtifactStore` from `core:artifacts-store`.
|
||||
- Segment files are append-only; `SegmentWriter`/`SegmentReader` own the on-disk format (`SegmentLayout`).
|
||||
- `SqliteArtifactIndex` maintains the content-hash → segment offset index; the SQLite file lives alongside the segments in the configured root dir.
|
||||
- `TailScanner` recovers the index after a crash by scanning the tail of the most recent segment.
|
||||
- `LivenessScanner` and `Evictor` handle compaction and space reclamation.
|
||||
- `CasConfig` is the only configuration surface; pass via `InfrastructureModule.createArtifactStore()`.
|
||||
- Environment observations (file existence, segment bytes) happen at call time and must not be re-read during replay — callers must record artifact content as events if replay correctness requires it (invariant #9).
|
||||
|
||||
## Work Guidance
|
||||
|
||||
Standard adapter rules apply (see parent `AGENTS.md`). No domain logic beyond storage mechanics belongs here.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :infrastructure:artifacts-cas:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,34 @@
|
||||
# infrastructure/inference/
|
||||
|
||||
## Purpose
|
||||
|
||||
Inference adapter layer. The root module provides `DefaultProviderRegistry` (registers `InferenceProvider` instances) and `FirstAvailableRoutingStrategy`. Submodules cover shared HTTP client infrastructure (`commons/`) and the llama.cpp server adapter (`llama_cpp/`).
|
||||
|
||||
## Ownership
|
||||
|
||||
Adapter for LLM inference backends. Implements `core:inference` interfaces. No dependency on other `infrastructure:*` modules.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- `DefaultProviderRegistry` implements `ProviderRegistry` from `core:inference`.
|
||||
- `FirstAvailableRoutingStrategy` is the default routing policy; extend only in `core:inference`, not here.
|
||||
- All LLM responses are proposals — they must be validated by the core before affecting state (invariant #7). Adapters return raw responses; they do not validate.
|
||||
- Network calls to the llama.cpp server are environment observations; results must be recorded as events by callers if replay must reproduce them (invariant #9).
|
||||
- Model lifecycle (spawn/own the llama-server process) lives in `llama_cpp/`; the autonomous scheduler is intentionally unbuilt (see root CLAUDE.md).
|
||||
|
||||
## Work Guidance
|
||||
|
||||
Standard adapter rules apply (see parent `AGENTS.md`). HTTP client code uses Ktor CIO; blocking I/O in `withContext(Dispatchers.IO)`.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :infrastructure:inference:test --rerun-tasks
|
||||
./gradlew :infrastructure:inference:commons:test --rerun-tasks
|
||||
./gradlew :infrastructure:inference:llama_cpp:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
- `commons/` — shared `ManagedInferenceProvider`, `ModelManager`, `ResourceProbe` (Nvidia/AMD), `ResidencyMode`; no separate AGENTS.md (sub-leaf, covered by this doc)
|
||||
- `llama_cpp/` — `LlamaCppInferenceProvider`, `LlamaProcess` (spawns/owns llama-server), `LlamaCppEmbedder`, `LlamaCppTokenizer`, `GbnfGrammarConverter`; no separate AGENTS.md (sub-leaf, covered by this doc)
|
||||
@@ -0,0 +1,31 @@
|
||||
# infrastructure/persistence/
|
||||
|
||||
## Purpose
|
||||
|
||||
Event store adapters for the correx event log. Provides `SqliteEventStore` (durable, production) and `InMemoryEventStore` (tests/dev). Also contains `LiveArtifactRepository`, which projects artifact state from the event log via `core:artifacts`.
|
||||
|
||||
## Ownership
|
||||
|
||||
Sole persistence adapter for `core:events` (`EventStore`). No other infrastructure module may write to the event log.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- `SqliteEventStore` implements `EventStore` from `core:events`; the SQLite file is the authoritative event log.
|
||||
- `InMemoryEventStore` is for tests only — not suitable for production use.
|
||||
- `LiveArtifactRepository` implements `ArtifactRepository` from `core:artifacts` by replaying events; it never persists state independently (invariant #1).
|
||||
- Schema migrations are the responsibility of this module; `JDBCHelper` owns connection utilities.
|
||||
- The event log is append-only: no updates or deletes to existing rows.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
Standard adapter rules apply (see parent `AGENTS.md`). All JDBC calls go in `withContext(Dispatchers.IO)`.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :infrastructure:persistence:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,31 @@
|
||||
# infrastructure/router/
|
||||
|
||||
## Purpose
|
||||
|
||||
Router infrastructure adapters. Currently contains one submodule: `turbovec/`, which provides `TurboVecL3MemoryStore` — a durable L3 (cross-session) memory store backed by a Python TurboVec sidecar process communicating over stdio.
|
||||
|
||||
## Ownership
|
||||
|
||||
Adapter for `core:router` L3 memory interfaces. No source in the root `router/` module itself; all code lives in `turbovec/`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- `TurboVecL3MemoryStore` implements `L3MemoryStore` from `core:router`.
|
||||
- The TurboVec sidecar is a Python process; `SidecarProtocol` defines the stdio JSON message protocol.
|
||||
- The bundled `turbovec_sidecar.py` script is extracted from the classpath to `~/.cache/correx/` at startup by `InfrastructureModule`.
|
||||
- Similarity search results are environment observations (ANN index query); callers must record retrieved memories as events if replay correctness requires them (invariant #9).
|
||||
- `TurboVecSidecarConfig` is the only configuration surface.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
Standard adapter rules apply (see parent `AGENTS.md`). Sidecar communication is async; never block the calling coroutine waiting for the process without `withContext(Dispatchers.IO)`.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :infrastructure:router:turbovec:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
- `turbovec/` — `TurboVecL3MemoryStore`, `SidecarProtocol`, `TurboVecSidecarConfig`; no separate AGENTS.md (sub-leaf, covered by this doc)
|
||||
@@ -0,0 +1,33 @@
|
||||
# infrastructure/tools/
|
||||
|
||||
## Purpose
|
||||
|
||||
Tool implementations and execution infrastructure. Provides `DefaultToolRegistry`, `DispatchingToolExecutor`, and `SandboxedToolExecutor`. Implements concrete tools: shell execution (`ShellTool`), web search (`WebSearchTool`, requires SearXNG), web fetch + HTML→Markdown extraction (`WebFetchTool`, jsoup), task management tools, and filesystem tools (in `filesystem/`).
|
||||
|
||||
## Ownership
|
||||
|
||||
Adapter for `core:tools`. Depends on `core:tools`, `core:events`, `core:approvals`, `core:sessions`, `core:tasks`, `core:artifacts`, `core:artifacts-store`. The `filesystem/` submodule is a dependency of this module.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- `DefaultToolRegistry` implements `ToolRegistry` from `core:tools`.
|
||||
- `SandboxedToolExecutor` wraps `DispatchingToolExecutor`; it enforces approval gates and records all tool side effects as events before returning (invariant #5).
|
||||
- No tool may execute a side effect without emitting an event — silent execution is not allowed.
|
||||
- Web search and web fetch results are environment observations; they must be recorded as events by callers to preserve replay determinism (invariant #9).
|
||||
- `ToolConfig` is the only configuration surface; pass via `InfrastructureModule.createToolExecutor()`.
|
||||
- `buildTools()` extension on `ToolConfig` assembles the full tool list; add new tools there, not in the registry directly.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
Standard adapter rules apply (see parent `AGENTS.md`). Network calls (web tools) use Ktor CIO client with `withContext(Dispatchers.IO)`. Shell tool executes OS processes — never suppress `CancellationException` in process wait loops.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :infrastructure:tools:test --rerun-tasks
|
||||
./gradlew :infrastructure:tools:filesystem:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
- `filesystem/` — filesystem read/write/list tools implementing `core:tools` contracts; no separate AGENTS.md (sub-leaf, covered by this doc)
|
||||
@@ -0,0 +1,31 @@
|
||||
# infrastructure/workflow/
|
||||
|
||||
## Purpose
|
||||
|
||||
Workflow and prompt loading adapters. Parses TOML workflow definitions into `core:transitions` execution plans (`TomlWorkflowLoader`, `ExecutionPlanCompiler`), loads prompt files from the filesystem (`FileSystemPromptLoader`), and validates plan structure (`PlanLinter`).
|
||||
|
||||
## Ownership
|
||||
|
||||
Adapter for `core:transitions` and `core:inference` workflow interfaces. Depends on `core:transitions`, `core:inference`, `core:events`, `core:artifacts`. Uses Jackson for TOML parsing.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- `WorkflowLoader` (implemented by `TomlWorkflowLoader`) is the interface for reading workflow definitions; implementations must not embed domain logic beyond parsing and structural validation.
|
||||
- `PromptLoader` (implemented by `FileSystemPromptLoader`) reads prompt text from disk; filesystem reads are environment observations — callers must record the loaded content as events if replay must reproduce the exact prompt (invariant #9).
|
||||
- `ExecutionPlanCompiler` converts the parsed `ExecutionPlanModel` into a runnable plan for `core:transitions`; compilation is deterministic given the same input model.
|
||||
- `PlanLinter` enforces structural rules (e.g. unreachable stages are rejected); linting failures throw `WorkflowValidationException`.
|
||||
- `PlanDerivedManifest` exposes the write manifest derived from a plan.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
Standard adapter rules apply (see parent `AGENTS.md`). Filesystem I/O in `withContext(Dispatchers.IO)`. TOML parsing errors must be surfaced as `WorkflowValidationException`, not raw Jackson exceptions.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :infrastructure:workflow:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
Reference in New Issue
Block a user