# 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), NFC normalisation and slug derivation (ADR-0015), sequence position (ADR-0016),
template composition (ADR-0019), feature locality (ADR-0027). Five more were recorded and then deferred
to `deferred-decisions.md`: cache validity, declared types, the cascade, taxonomies, extras.

## 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.