2.6 KiB
Engine design review — open items
Status: parked Raised: 2026-07-28
One review, many decisions. Each item below graduates independently: when one is settled it becomes an ADR (or a change to its owning doc) and is struck from this list. When the list empties, delete the file. Graduated so far: site root external to the engine repo (ADR-0011), Effect as the sixth primitive (ADR-0012), the cache validity model (ADR-0013), declared content types (ADR-0014), NFC normalisation and slug derivation (ADR-0015), sequence position (ADR-0016), the settings cascade (ADR-0017), taxonomies and feeds (ADR-0018), template composition (ADR-0019), feature locality (ADR-0027).
Why it came up
The harness was written for a generic blog engine and then aimed at a site hosting blog posts, webcomics, art, literary writing, standalone pages and IndieWeb status notes, with a featureset meant to keep evolving. Several things that are cheap to decide now get expensive once content exists or the first URL is published.
Decide before Arc 1 writes code
Pagination URL shape. Undecided and permanent — /posts/page/2/ versus a query parameter. ADR-0008
settled the bundle shape only, and ADR-0016 settled that a slug may contain slashes; this is the last
open piece of the permalink space.
Decide during Arc 1–2, as the code arrives
UI chrome strings and Bengali collation. i18n covers content variants, not chrome ("Next chapter", "Read more") — a small message catalog, decided before templates multiply. Separately, byte sort is wrong for Bengali indexes: adopt collation, or decide explicitly that ordering is date-only.
Cheap, whenever
A check command in the engine. Missing required fields per type, image without alt, broken
internal link, dangling series reference, orphaned asset, slug collision, non-normalised filename,
alias colliding with a live URL. A walk over already-loaded bundles. Explicitly not verify.sh:
that gate answers "is the engine sound", this answers "is my content sound", and it runs against a
site root the engine repo cannot see.
Search as a static artifact. A prebuilt index file shipped with the site needs no running service — the most sovereign option available, and it satisfies ADR-0010 trivially because the index is derived. An Effect (ADR-0012) builds it.
No-JS reading experience. Server-rendered prev/next always present; keyboard navigation and prefetch as enhancement only. Decide before the comic reader exists, not after.
Dropped
Binary assets in git. Now purely a decision about the site repo, outside the engine repo entirely, so the harness has no stake in it.