init

ideas/engine-design-review.md

@@ -0,0 +1,50 @@
+# 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.