Skip to content

E17 — Local-first web-app extraction

State Active
Start Date 2026-10-31
Feature State Iteration Stories
F17.1 — Problem rows from an exception hierarchy Closed release-8 3 Closed
F17.2 — Single-owner thread actor Closed release-8 2 Closed
F17.3 — TaskPool.map_settled Closed release-8 2 Closed
F17.4 — SQLite engine and embedded migrations Closed release-8 4 Closed
F17.5 — Safe filesystem mutation Closed release-8 3 Closed
F17.6 — Durable in-process job queue New deferred 3 New

Apollo, a local-first FastAPI music-library application, wrote several pieces of generic plumbing that any single-user FastAPI tool would write again: problem rows built from a domain exception hierarchy, a single-owner thread for a library that is not thread-safe, a per-item failure capturing parallel map, SQLite engine and migration setup, safe filesystem mutation helpers, and a durable in-process job queue. This epic moves them into the packages that already own their neighbours. Each feature ships alone.

Apollo's rebuild proceeds on the pins it has today and does not wait for any of this. It adopts each piece after the feature is released and the application's pinned rn-forge-* tags are bumped; until then it keeps its own copy.

Back to the work index

F17.6 is tagged deferred; its entry criterion is that a second application needs the queue.

Context

Placed as its own epic, not in E6. E6 is tagged deferred as a whole and is scoped to two named pieces of plumbing, each in one package, that several applications had already written; its entry criterion is the owner scheduling either of those two. These features span four packages, come from one application's review, and are not deferred, so putting them under E6 would either make them wait on E6's criterion or force E6 to lose its tag. F17.6 builds on F6.2 and links to it.

Considered and rejected

  • One feature for the whole epic. The features touch different packages, and an application can want the thread actor without the SQLite helpers.
  • A new rn-forge-local package. Each piece belongs beside what it extends: the registry in rn-forge-web, the runtime helpers in rn-forge-commons, the engine in rn-forge-sqlalchemy. A package of leftovers would duplicate their boundaries (ADR-0001).
  • Typed application state is not part of this epic; it is F25.1.
  • Single-consumer conveniences: a worker-count helper, a default_registry keyword for lookup errors, and tool-version probing. Each is a line or two in the application, or a heuristic only Apollo needs; see F17.1, F17.3 and F17.5.