Skip to content

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.

  1. 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.
  2. 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.
  3. 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-cli builds commands from a generic [cli] table, while lifecycle verbs, their [lifecycle] table and build_tool_app belong to rn-forge-tooling. Rendering templates and owning generated files are not tooling. An application that writes files can need both, so rule 1 places them.
  4. 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.
  5. 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).