F18.1 — Templates, generation and state move to commons
| State | Closed |
| Parent | E18 |
| Iteration | Release 6 |
| Start Date | 2026-10-25 |
| Closed Date | 2026-10-25 |
| Predecessors | — |
| Source | Owner decision, 2026-10-24 (ADR-0002, rule 3 as amended) |
Stories: 3 Closed
| Story | State | Depends on |
|---|---|---|
S18.1.1 — Move the template engine, with autoescape, cached and brace-safe errors |
Closed | — |
S18.1.2 — Move the generation engine and StateStore |
Closed | S18.1.1 |
| S18.1.3 — Import boundaries that can break | Closed | S18.1.2 |
Rendering templates and owning generated files move from rn-forge-tooling to
rn-forge-commons, so an application that writes files from templates gets the
whole capability without the CLI and installer layers:
TemplateEnginemoves torn_forge.commons.text.templates, behind atemplatesextra.- The generation engine (artifacts, plan, apply) moves to
rn_forge.commons.generation, which the facade does not import. StateStoremoves torn_forge.commons.fs.state.
Tooling keeps the lifecycle verbs and install mechanics. The engine gains
autoescape and a process-wide cached constructor, and stops crashing on a
Jinja error containing a brace. The import contracts that guard these modules
are written so they can actually break.
Context
ADR-0002's rule 3 named "file-generating" layers as tooling. On 2026-10-24 the owner dropped that word. A web application that generates files from templates wants plan, diff, atomic apply with rollback, and drift detection, as much as a developer tool does. Nothing in those signatures is CLI or installer policy, so rule 1 places them in commons.
The move costs no new dependency: generation and state import only the
standard library and commons. The facade must not import generation or text,
because it imports eagerly and a re-export would load the generation engine,
Jinja and markdown-it for every commons user, including kiln's doctor checks.
The contracts name sibling source modules because import-linter 2.15 never
breaks a forbidden contract whose forbidden module sits inside its source
package (checked 2026-10-24); the root .importlinter header records the rule,
and a subprocess test covers the package __init__ modules, which no contract
can. TemplateEngine.cached exists because a jinja2.Environment compiles each
template once and kiln wrapped the constructor in functools.cache in ten
modules. Errors are brace-safe because AppException formats its message with
str.format, so a Jinja message containing a brace raised ValueError.
Design
The feature shipped as designed. The rn-forge-commons generation guide
(docs/guides/generation.md), text guide (docs/guides/text.md) and API
reference document the result; the root .importlinter holds the contracts.
Moves
TemplateEngine moved to rn_forge.commons.text.templates, the generation
package to rn_forge.commons.generation and StateStore to
rn_forge.commons.fs.state, with their tests and docs, using git mv. Class
and function names did not change.
Template engine changes (text/templates.py)
autoescape (default False) was added, TemplateEngine.cached returns one
shared engine per set of hashable arguments, and a Jinja error raises
RenderError("{}", exc).
Facades
The commons facade re-exports StateStore and imports neither generation nor
text; tooling dropped RenderError, StateStore and TemplateEngine.
Manifests
Commons gained the templates extra (jinja2), and tooling dropped jinja2.
Import contracts (root .importlinter)
commons-is-runtime-neutral was replaced, and commons-core-has-no-extras,
generation-core-renders-nothing and a corrected data-core-has-no-adapter
were added, each naming sibling source modules.
Facade import tests
Subprocess tests in commons and data assert that importing the facade loads no generation, text, Jinja, Markdown or pandas module.
Docs
The root README, the workspace architecture page, the tooling and commons guides and the extras table were updated for the move.
Changelogs ([Unreleased])
The commons, tooling and data changelogs record the added modules and extra, the brace fix, the breaking removal from tooling and the corrected contract.
New tests (beside the moved ones)
tests/text/test_templates.py gained tests for autoescape, cached and
brace-safe errors.
S18.1.1 — Move the template engine, with autoescape, cached and brace-safe errors
State: Closed
Acceptance:
- The template rows of Moves, the engine changes, the manifests and the template docs and changelog lines hold.
tests/text/test_templates.pypasses.
S18.1.2 — Move the generation engine and StateStore
State: Closed · Depends on: S18.1.1
Acceptance:
- The generation and state rows of Moves, the facades and the remaining docs and changelog lines hold.
- The moved tests pass unchanged except for their imports.
- Tooling's remaining tests pass.
S18.1.3 — Import boundaries that can break
State: Closed · Depends on: S18.1.2
Acceptance:
- The contracts and facade tests under Design hold, and
lint-importskeeps every contract. - Each new or rewritten contract is shown to break, by hand, once, before
merging: add
from rn_forge.commons.generation import Plantorn_forge/commons/fs/paths.py, andimport rn_forge.data.pandastorn_forge/data/excel.py.lint-importsmust report both contractsBROKEN; then revert the lines. Record the run in the commit message.
Acceptance
set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
uv run pytest -q packages/rn-forge-commons/tests/text/test_templates.py # S18.1.1
test ! -e packages/rn-forge-tooling/src/rn_forge/tooling/templates.py # S18.1.1
absent '^\s*"jinja2' packages/rn-forge-tooling/pyproject.toml # S18.1.1
uv run pytest -q packages/rn-forge-commons/tests/generation packages/rn-forge-commons/tests/fs/test_state.py # S18.1.2
test ! -e packages/rn-forge-tooling/src/rn_forge/tooling/generation # S18.1.2
test ! -e packages/rn-forge-tooling/src/rn_forge/tooling/state.py # S18.1.2
absent 'rn_forge\.tooling\.(templates|generation|state)' packages README.md docs/architecture docs/guides \
--glob '!**/CHANGELOG.md' --glob '!**/changelog.md' # S18.1.1 S18.1.2
uv run pytest -q packages/rn-forge-tooling # S18.1.2
uv run pytest -q packages/rn-forge-commons/tests/test_facade.py packages/rn-forge-data/tests/test_facade.py # S18.1.3
uv run lint-imports && uv run pyright # S18.1.1–S18.1.3
(cd packages/rn-forge-commons && uv run --group docs mkdocs build --strict) # S18.1.1 S18.1.2
(cd packages/rn-forge-tooling && uv run --group docs mkdocs build --strict) # S18.1.1 S18.1.2
uv run --group docs mkdocs build --strict # S18.1.1 S18.1.2
The by-hand BROKEN check in S18.1.3 is not scripted.
Considered and rejected
- Keep
rn_forge.tooling.*aliases for one release. ADR-0002 rule 5 forbids them, and kiln, the only consumer, moves its imports in one change. - Put
generationbehind an extra. It needs no third-party package. Keeping it out of the facade is what keeps it off a commons user's import path, and the facade test proves it. - Re-export
generationfrom the facade. The facade imports eagerly. Every commons user, a web worker included, would load the engine to get aFinding. - A package of its own (
rn-forge-generation). It fails ADR-0011's first test: it has no dependency set of its own. StateStoreundergeneration. It is a generic locked JSON key-to-entry store with no generation vocabulary in its signature, sofsholds it.