Codebase structure

This page says which package should own a change.

Choose a destination #

reef/ holds every shared mechanism, including the harness evolution engine at reef/train/cordis_backend/. Paper-backed methods live in separate packages under recipes/ (sao, tttd, openclawrl, skillclaw) with that method's recipe, processor, step preparer, and, for weight methods, the slime/ subpackage only the training plane imports. Nothing under reef/ imports a method package.

Reef is organized around an application kernel and three capability domains, not a strict stack of top-level packages. The arrows below show the primary composition and use paths; they are not an exhaustive Python import graph:

Rendering diagram…

Method packages provide policy through reef/recipe and may bind reef/train machinery directly. HTTP and CLI entrypoints compose Reef through reef/service; the transport-free dispatcher and scenario aggregate coordinate serving, evolution, and state. reef/service also imports reef/artifact directly to stream artifact bytes.

Concrete integrations may depend on shared contracts; shared contracts never import a concrete integration.

Package	Owns	Does not own
reef/core/	shared value types, wire shapes, artifact identity, root errors	storage, I/O, runtime behavior
reef/service/	HTTP routes, auth, streaming, process lifecycle	training methods or domain logic tied to aiohttp
reef/scenario/	scenario binding, commit ordering, recovery, checkpoint policy	training algorithms, repository implementations
reef/recipe/	the contract a method implements, dotted class resolution, and runtime instance binding	any particular method
reef/train/	the trainer loop, processor engines, batch types, backend integrations	HTTP endpoints, deployment configuration parsing
reef/runtime/	backend-neutral inference and training contracts	a concrete training stack integration
reef/surface/ \| delivering a published artifact to the \| proposing, evaluating, or \| process or client that uses it \| selecting updates
reef/artifact/ \| artifact bytes, repositories, \| commit policy or delivery \| materialization, release heads \| behavior
reef/harness/	harness descriptors, tree rendering, episodes, trajectories	recipe policy, the release chain
recipes/	one method per package: recipe, processor, preparer, and its runnable examples	shared machinery, or another method
tests/	repository-level tests grouped by responsibility	tests hidden inside an integration subtree
docker/	container and GPU environment setup	Python dependency declarations

The extension points those packages expose are in Python API.

Is it a value or error needed by unrelated layers without behavior attached? Put it in reef/core/.
Does it own scenario state, commit ordering, recovery, or rollback? Put it in reef/scenario/.
Does it persist or materialize versioned bytes? Put it in reef/artifact/. If it decides how consumers activate those bytes, put that behavior in reef/surface/ instead.
Does it define a backend-neutral model-service contract? Put it in reef/runtime/. Put implementation tied to a concrete training stack in its own reef/train/<integration>/ subtree. reef/train/cordis_backend/ is the general harness evolution engine; its composition core derives from cordis 4.0.0-rc.8 with the conformance map in its compose/UPSTREAM.md. reef/train/slime_backend/ is the weights counterpart.
Does it turn records and feedback into a batch or step signal? Put it in reef/train/processors/ or reef/train/algos/. A recipe selects and binds that machinery; it should not reimplement it.
Is it HTTP-specific? Keep the aiohttp adapter in reef/service/routes/ and put transport-independent behavior in a service or domain object.
Does it orchestrate a benchmark, task, grader, or external environment? Keep it under recipes/<name>/examples/ or in the external harness.

Repository-level homes #

Code for a concrete training integration lives together under reef/train/<integration>/, but its surrounding files remain at repository level:

internal integration tests in tests/<integration>/;
import and packaging contracts in tests/plugin_contracts/;
service-facing contracts in tests/reef_service/;
the learn-nothing deployment stacks, and the smallest example around them, in recipes/basic/;
configuration for one runnable deployment under recipes/<name>/examples/;
container and environment setup under docker/; and
Python dependencies, package data, and plugin entry points in pyproject.toml.

Do not copy third-party source into an integration subtree. Pin or declare the dependency in pyproject.toml and keep Reef-owned adapters local to the integration.

Where the detailed rules live #

Each package's __init__ docstring states the boundaries it holds and how to extend it; there are no READMEs under reef/. Design pages for the two packages that need more than a docstring are Surfaces and Processors; the extension points every package exposes are in Python API, and the public harness wire contract is HTTP API. The top-level README shows how the cookbook methods sit beside reef/.

reef/train/cordis_backend/ is the general harness evolution engine; its composition core derives from cordis 4.0.0-rc.8 with the conformance map in its compose/UPSTREAM.md. reef/train/slime_backend/ is the weights counterpart.

Adding a new subpackage under reef/ or a new method under recipes/ requires an RFC that states which layer owns the behavior.