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
|
||||
Reference in New Issue
Block a user