ADR-0083: Backend layers are enforced through kernel types, ports and one package per layer
Context and Problem Statement
app/CLAUDE.md draws the backend as five layers over a shared kernel:
- HTTP;
- Services;
- Execution;
- Executors;
- Infra.
Two pending Konsist rules check this picture (ADR-0082). The layering rule says each layer imports only itself, the layers below it and the kernel. The cycle rule says the top-level packages homer.app.* import each other without cycles. When they were introduced, the code broke both: 39 layering and 11 cycle findings. The code paths behind them:
The kernel imported upward.
models/usedservices.TagValidation,services.stripUrlSecretsandrunners.external.RunnerProtocol, which closed themodels ↔ servicesandmodels ↔ runnerscycles.Execution and Executors call Services directly.
ProcessExecutor,AgentExecutor,CommandExecutorFactory,LlmHarnessExecutorandRunAgentExecutoruse these Services types directly:ProcessManager;QuestionsService;LlmTelemetryService;AgentRunStarter;AgentsService;Authorizer;- the telemetry interfaces.
ProcessManageris also where the run's domain types live:ProcessInfo,ExecutionInfo,ProcessStatusandProcessCreationResult. Any lower layer that names one of them imports Services.Infra calls up. The Kubernetes runner and its state sink write through
ProcessManager, and the external runner domain feeds the claim queue (Execution).One package holds two layers.
services/contains the Services layer and most of the Infra layer:Workspace,SecretRedactor,FileOperations,TextCompiler,WhenEvaluator, the LLM stream helpers and others.Process(Execution) lives there too. Executors import about 70 of these names, soservices ↔ executorsandservices ↔ runnersare package cycles no single import can break.
Decision Drivers
- The diagram should describe the code and be checked, rather than left as a hope (ADR-0082).
- Dependencies should point down. A layer that needs something from above declares what it needs, and the layer above provides it.
- Each step should land on its own and keep the build green, because other branches are in flight.
- Behavior, the HTTP API, persistence and the security gates must not change.
Considered Options
- Ports and kernel types, then a package per layer, in three steps.
- Relax the rules: drop the cycle rule and let Execution and Executors import Services.
- One big move: all of option 1 in a single merge request.
Decision Outcome
Chosen option: 1, in three merge requests. Each one leaves main green.
Step 1: kernel
TagValidationandstripUrlSecretsmove tomodels/.- The secret-screen floor becomes
MIN_SCREENED_SECRET_LENGTH, defined in the kernel and reused bySecretRedactorandTagValidation. - The pull-runner long-poll window becomes
RUNNER_LONG_POLL_SECinmodels/, andRunnerProtocol.POLL_SECis defined as that value. - The kernel imports nothing outside itself.
Step 2: layering
The layering rule becomes required.
- The run's domain types move to the kernel.
ProcessInfo,ExecutionInfo,ProcessStatus,ProcessCreationResultand the other data classes nested inProcessManagermove tomodels/. They describe a run, and every layer reads them. - A lower layer that needs a higher one declares a port. The port is a narrow interface in the lower layer's own package that lists only the calls it makes. The higher layer implements the port, and
di/AppModule.ktbinds it. Two examples:ProcessManagerimplements the Execution-side record of a run's steps and status.- The services implement the sub-run start that
RunAgentExecutorneeds.
- The diagram is corrected only where a type's nature was misfiled. A wrapper over an external system, such as the OpenTelemetry and Langfuse clients, is Infra. An in-memory execution gate is Execution. Each move between rows names its reason in
app/CLAUDE.md. A type is never reclassified only to silence a finding.
Step 3: cycles
The cycle rule becomes required, and the pending lane goes away.
- The Infra code in
services/moves to its own package,homer.app.infra. Processmoves next to the rest of Execution.- With the ports from step 2,
executorsandrunnersthen import nothing fromservices, andinfraimports only the kernel. - The pending lane is then empty. The
architecture-backend-pendingcheck and itsquality-gateline are removed, asapp/CLAUDE.md§ Architecture tests prescribes.
Done (2026-10-13): the cycle rule is required with zero findings, and the lane is empty.
- 53 files moved to
infra/,services/interfaces/included. Process,LockManager,ParallelRunsManagerand their implementations moved toexecutors/. Three more ports keep them out ofservices:RunWorkRecordsandRunKiller, implemented byProcessManager.RunWorkRecordsshares the guarded status write,GuardedStatusWrite, withRunRecords;QuestionRegistration, implemented byQuestionsService.
- Nine files the package rule had filed as Infra stayed in
services/and count as Services. Eight call services: the MCP tool factories andMcpRunTools,DispatchGates, the agent-file gates,RunLivenessandProcessGraphInspectRunner. The ninth,LlmSpanEmitter, calls none; it is the span writerLlmTelemetryServicewas split into for size, and only that service builds it. - The package now gives the default layer:
services/is Services, andinfra/is Infra.
Consequences
- Good: the diagram becomes a checked fact, and a new dependency that points up fails the build at the import that adds it.
- Good: ports document exactly what Execution needs from Services, which also makes the executors testable against small fakes.
- Bad: step 2 renames widely used types (
ProcessManager.ProcessStatusbecomesProcessStatus), and step 3 moves dozens of files. Both mean import churn, and branches open at the time must merge through it. Splitting the work into three steps keeps each conflict set small. - Bad: a port is one more interface to keep in step with its implementation. Each port holds only the calls its caller makes.
Pros and Cons of the Options
Relax the rules
- Good: no churn.
- Bad: the diagram stays prose, which is the drift ADR-0082 exists to stop. The package cycles also hide real coupling, for example an executor reaching into
AgentsService.
One big move
- Good: done once.
- Bad: one diff too large to review, and every other branch hits all of its conflicts at once.
More Information
- ADR-0082 covers the report-first mechanism and the pending lane.
app/CLAUDE.md§ Layered architecture and § Architecture tests describe the diagram and how each file's layer is read.