ADR-0002: Code is placed by what its API contains, and boundaries are one-way
Status: accepted (2026-09-12) · Scope: every rn-forge-* package,
existing and future
Decision
These rules decide which package a module belongs in. The current package graph
is architecture, not part of this decision:
workspace boundaries describes it, and the root
.importlinter enforces it.
- Place by signature, not by caller. A module's package is decided by what its API's signature contains, not by who calls it today. A lock or an atomic symlink carries no installer policy, so it lives in commons even while only developer tools call it.
- Protocols low, adapters beside their technology. A protocol lives in the lowest package that can define it without an adapter dependency. A concrete adapter lives with the technology it integrates.
- Runtime never depends on tooling. Runtime packages hold what a deployed
application needs. Command-line and installation layers sit on a separate
branch that runtime packages never import. A generic layer carries no
product policy:
rn-forge-clibuilds commands from a generic[cli]table, while lifecycle verbs, their[lifecycle]table andbuild_tool_appbelong torn-forge-tooling. Rendering templates and owning generated files are not tooling. An application that writes files can need both, so rule 1 places them. - Framework-free means framework-free. A package that defines a framework-neutral contract imports no web framework, and sibling framework packages do not import each other.
- No compatibility re-exports, in any direction. When a symbol crosses a package boundary, it moves; it is not aliased.
A new package states its place in the graph by these rules and adds its
contracts to .importlinter. That does not change this record.
Consequences
A deployed application can use runtime packages without the command-line and
installation layers, and a batch application using only [cli] does not import
tooling. Code that only some applications want sits in commons behind an extra,
or in a module the facade does not import (ADR-0003), rather than
in tooling. A new shared protocol cannot be dictated by its first
implementation. Package dependency declarations and the import contracts must
agree.
Influences
This decision shapes E1 foundation and boundaries, E3 framework adapters, E5 tool lifecycle, E7 Azure adapters and E11 framework code generation. ADR-0003 governs optional dependencies inside each package.
Alternatives considered
One large runtime package would make CLI and file-writing dependencies available
to services that do not need them. Compatibility re-exports would hide a move
while letting imports point against the graph. Placing a module by its current
callers put DirectoryLock and atomic_symlink in tooling in the first
extraction; the development-layer review moved them to commons because nothing
in their signatures is installer policy. A CLI-owned [cli.lifecycle] table
mixed product policy into the generic parser and needed a string target to
route to tooling; it was retired on 2026-09-22. Keeping the template engine, the
generation engine and the state store in tooling, under rule 3's earlier
"file-generating" wording, made a web application that renders files from
templates install the CLI and installer layers. That application wants plan,
diff, atomic apply and drift detection too, and nothing in their signatures is
CLI or installer policy.
Background
Decided 2026-09-12 in the review of the development-layer split and landed at
f59c40f; recorded here 2026-09-24. On 2026-09-26 this record dropped its
package-by-package graph so a new package no longer edits it, and absorbed the
lifecycle-ownership decision as an application of rule 3. On 2026-10-24 rule 3
dropped "file-generating" from the tooling branch. The template engine, the
generation engine and the state store move to commons under rule 1
(E18).