File reference, one page per source file

This section covers every file in loopctl/src/, the companion crates under crates/, and the supporting trees, all in plain words. Those companions are derive, sqlite, hnsw, client, and vector, which moved there in 0.4.0.

Each page tells you what the file is, lists its key items, records its behavior notes, and links to the deep-dive article.

You reach for this section when you sit in the code and want to know what the file in front of you does. It is also how you find where something lives.

You open a page here to learn what a file owns, which items it exports, and how it behaves. Each page follows the same shape, so you can skim two dozen of them and still know where you are.

Every page keeps the same three sections. The first section names what the file holds and what it sets up for you. The second records how it handles failures, cancel, and configuration, which is where the surprises live.

Read those notes before you change the file. They tell you what the code assumes, and they mean what they say: a page that says a lock is never held across a call means the authors checked it.

The tables below gather those pages by area, and every row links to the deep dive that explains the reasoning.

The crate root and foundations

File	One line
lib.rs	Crate root: module wiring and the feature gates.
message.rs	The conversation data model: Message, parts (incl. signed thinking), roles, tool content, retention.
error.rs	LoopError: the one error enum, plus the lock-poison policy.
config.rs	SessionConfig: system prompt, context window, compaction knobs.
cancel.rs	CancelSignal: cooperative cancellation.
capabilities.rs	Small traits asking “does this bundle have X?”
contributor.rs	ContextContributor: per-turn message injection.
attachment.rs	Pinned per-turn context (file / memory / todo) that compaction cannot touch (0.4.1).
numeric.rs	Internal safe-math helpers (not public).
managers.rs	LoopManagers: the bundle of optional components (ask resolver, clock/id seams).
presets.rs	Constrained/Frontier profiles + GoalReminder (Constrained is the default wiring since 0.4.0).
budget.rs	BudgetGate: soft/hard spend lines consulted before each request.
ask.rs	The external-approver channel: park a run at a hook’s ask, resume on the answer.
determinism.rs	Clock/IdGen/Rng seams: same run, same bytes.
manifest.rs	The loop.yaml model: parse → merge → interpolate → validate → hash [feature: manifest].

Talking to models

File	One line
api.rs	The ApiClient trait and request/response carriers.
api/error.rs	ApiError + ErrorCode: provider errors classified.
stream.rs	Stream events, deltas, stop reasons, the accumulator.
stream/handler.rs	StreamHandler: retries, timeouts, fallback.
stream/rate_limit.rs	Token-bucket rate limiter.
structured.rs	Structured (JSON) output: trait, formats, constraints.
provider.rs	Provider profiles + shared HTTP plumbing.
provider/openai.rs	OpenAI client (base of the compatible family).
provider/anthropic.rs	Anthropic client (base of Z.ai path).
provider/gemini.rs	Gemini client.
provider/bedrock.rs	AWS Bedrock client (signing, two wire paths).
provider/embeddings.rs	OllamaEmbedder + OpenAiEmbedder: the real EmbeddingProvider backends.
provider/sse.rs	The SSE reader shared by the clients.
provider/grammar.rs	Grammar constraints for local samplers.

The engine

File	One line
engine.rs / engine/core.rs	Module roots (re-exports).
engine/core/machine.rs	The brain: the pure state machine.
engine/core/lifecycle.rs	Loop trait, Run/Session/Turn, RunConfig.
engine/core/outcome.rs	Outcome → error translation.
engine/bare.rs	The hands: the driver loop and its handlers.
engine/bare/llm_turn.rs	Building and sending one model request.
engine/bare/dispatch.rs	The tool-call pipeline and recovery.
engine/bare/compact.rs	The driver side of compaction.
engine/bare/prune.rs	The no-LLM tool-output reclamation pass (opt-in PruneConfig).
engine/bare/emission.rs	All observer/hook fan-out.
engine/bare/config.rs	The set_*/with_* builders, temp dir.
engine/bare/model_switch.rs	Atomic mid-session model change.
engine/bare/steering.rs	The Steering slot: host guidance drained at turn boundaries (0.4.1).
engine/bare/tests.rs	The engine’s own test suite (in-file).

Tools and safety

File	One line
tool.rs	The Tool trait, outputs, errors, contexts, retention classes.
tool/builtin/read.rs	ReadTool + ContentSource: line-aware reads over any source [feature: builtin_tools].
tool/builtin/fs.rs	Write/Edit/MultiEdit/FileViewer + FileSource [feature: fs_tools].
tool/builtin/search.rs	Glob/Grep/CodeSearch/Tree over a SearchSource [feature: search_tools].
tool/builtin/shell.rs	Shell + Jobs over a ShellBackend [feature: shell_tools].
tool/builtin/think.rs	ThinkTool: the planning scratchpad (Think since 0.4.0) [feature: builtin_tools].
tool/registry.rs	ToolRegistry + FnTool (runtime-mutable since 0.4.1).
tool/selector.rs	The per-turn tool advertisement: ToolSelector, KeywordSelector, the async family (0.4.1).
tool/permission.rs	PermissionCheck + GateDecision: the decision type and its audit record.
tool/grant.rs	GrantStore: persisted approvals with narrow scopes [feature: file_grants].
tool/health.rs	Per-tool stats and circuit breakers.
tool/shield.rs	The safety shield trait + UnixShield.
middleware.rs	The pipeline core: trait, context, builder.
middleware/tool_call.rs	The pipeline’s innermost core (registry call).
middleware/timeout.rs	Per-call deadline.
middleware/permission.rs	Policy enforcement layer.
middleware/output_limit.rs	Output size cap.
middleware/unknown_tool.rs	“Did you mean…?” suggestions.
middleware/memoize.rs	The tool-result cache.
middleware/verify.rs	Post-write verification.
middleware/redaction.rs	Secret scrubbing.
middleware/shield.rs	The shield’s pipeline wiring.
detection/loop_detector.rs	Repeated-operation detection.
detection/convergence.rs	Repeated-answer detection.
detection/manager.rs + detection.rs	The detection facade and the module-root re-exports.
fallback.rs	Model-level circuit breaker + chain.
reflection.rs	Reflector + RecoveryStrategy traits.
reflection/llm.rs	The model-powered reflector.
reflection/backoff.rs	Exponential backoff strategy.

Watching and extending

File	One line
observer.rs + observer/context.rs	The LoopObserver trait + event payloads.
observer/hub.rs	EventHub: one observer feeding a broadcast LoopEvent stream.
hooks.rs + hooks/context.rs	The Hook trait + contexts.
hooks/executor.rs	First-block-wins execution.
hooks/builtin/*	AutoCommit, Blocklist, Confirmation, Logging.
memory.rs + entry.rs + builtin.rs + score.rs	The memory trait, entries, in-memory store, shared retrieval scorer.
memory/file.rs	FileMemoryStore: JSONL persistence that survives a restart (file_memory).
memory/trajectory.rs + memory/trajectory/sink.rs	TrajectoryObserver: each run as a serializable record (memory + JSONL ledger).
memory/consolidate.rs	Quality scoring, category-weighted decay, duplicate merging: the consolidation primitives.
memory/extractor.rs	Mines learned memories from recorded runs (MemoryExtractor).
memory/vector.rs	EmbeddingProvider + VectorIndex primitives and reference impls (vector_index).
memory/vector_memory.rs	VectorMemoryStore: the semantic LoopMemory backend + the golden-set bar (vector_memory).
memory/search_tool.rs	SearchMemoriesTool: the model-callable memory search.
compact.rs + types.rs + truncating.rs	Compaction manager, outcome types, truncator.
compact/qa_summarizer.rs	QaSummarizer: the three-step LLM compactor.
compact/structured_summarizer.rs	StructuredSummarizer: sectioned summaries with stable headings.
compact/fallback.rs	FallbackCompactor: the never-fail chain with TerminalCapture.
compact/demote.rs	DemotionSink + MemoryDemotionSink + render_evicted.
compact/rolling.rs	RollingCompactor: the maintenance-cadence compactor.

Integration and support

File	One line
mcp.rs	MCP client side (import foreign tools).
mcp/server.rs	MCP server side (serve your registry).
mcp/convert.rs	The type conversion layer between worlds.
testing.rs	Mocks and fixtures.
crates/derive/src/*	The #[derive(Tool)] macro crate.
crates/sqlite/	loopctl-sqlite: durable SQLite LoopMemory (WAL, FTS5, ranking parity).
crates/client/	loopctl-client: the shared daemon client (UDS REST + SSE, both modes).
crates/hnsw/	loopctl-hnsw: the HNSW VectorIndex companion.
crates/vector/	loopctl-vector: Qdrant + pgvector backends (side workspace).
examples & tests	The runnable tour.