bdeshi
a54d174253
The entry said to measure first and put the number in the commit, so: a plain page renders in 14µs, a twelve-picture gallery in 1.23ms. Of that, ~102µs per picture was reading, hashing and decoding bytes the previous request had already read. Remembering that one fact — keyed by path, size and modification time — brings the same gallery to 63µs. 19.5× faster, 21× fewer bytes allocated, twenty-odd lines. After which nothing is slow enough to justify caching whole pages, so ADR-0044 declines the page cache and leaves the parked validity model parked, now with a measurement rather than an intuition behind its trigger. That parked model has five axes and was written before any code existed. The problem it would have been built for turned out to be one repeated file read. Benchmarks live in internal/web so they measure through the real handler, which is also what conventions.md wants before any cache goes in the render path. The invalidation risk has its own test: an edited picture is a different key, so the memo cannot serve yesterday's dimensions. Everything runs clean under -race, since the map is read by concurrent requests.
7.7 KiB
Deferred decisions — recorded intent, not binding shape
Status: parked Raised: 2026-07-30
Five ADRs were written before any code existed. They describe a direction worth keeping, but their shape is speculation: the harness's own rule is no abstraction before its second concrete use, and a field-level specification of an unbuilt mechanism breaks that rule in prose instead of code.
Their entries in decisions.md are now Status: intent stubs pointing here, so citations still resolve
and nothing is lost. Each returns as a full ADR when something implements it — and the implementation,
not this file, decides the shape.
Cache validity model
Status: still parked, and now with a measurement behind it (ADR-0044). Rendering a page costs ~63µs once repeated picture inspection is remembered; the parked model solves a problem the site does not have. Its trigger is a render exceeding a few milliseconds, or output that stops being a pure function of content.
Deferred because no cache exists, and the harness forbids one until requests feel slow.
Cache validity is one record with five axes
Date: 2026-07-28 · Status: accepted
Decision: a cache entry carries a validity record — content dependencies, interaction fragment refs,
valid-until, engine+template epoch, and a cacheable flag — and is served only while all five hold.
valid-until is the minimum of the windows the render's Stages declare; Stages reach the clock through
an injected accessor, never time.Now(). An optional scheduled Effect may pre-warm entries, but
scheduling is never what makes a page correct.
Why: invalidation has five causes, not one. Content edits and interactions were already modelled; time
(old-article banner, relative dates, future-dated publication), epoch (a template fix silently serving
old HTML), and opt-out (search, a random-page route) were not. A scheduled re-render sweep expresses
only the time axis, and coarsely — relative dates would need a sweep finer than their own granularity.
Consequence: cheap — the record maps onto HTTP semantics (ETag from deps plus epoch, Expires from
valid-until, no-store for opt-out), so a reverse proxy or CDN in front is correct with no extra
code, and a new time-dependent Stage needs no central registry because windows compose by minimum.
Expensive — the Stage contract gains a return channel, and a Stage that reads the clock without
declaring a window would serve staleness silently, which is why the clock accessor is enforced by
verify.sh rather than trusted.
Revisit if: windows cannot express some invalidation cause — then add an axis, do not add a mechanism.
Declared content types
Deferred because the MVP can default a type from its section directory; a declaration file earns itself at the seventh type or the first per-type override.
Content types are declared, not coded
Date: 2026-07-28 · Status: accepted
Decision: each content type is a declaration — section, default view, ordering rule, feed membership,
required frontmatter, whether titleless is legal, applicable taxonomies. The binary embeds a default set
(post, comic, art, writing, page, status); a declaration file in the site root extends or
overrides it. Adding a type costs a declaration plus a template and no core change; an unparseable or
incoherent declaration is a loud startup failure.
Why: six types already carry per-type behaviour, described in prose. Prose becomes either a switch type
in the core — forbidden, and it would grow with every new type — or unwritten template convention. A
declaration is the only form that keeps the seventh type as cheap as the sixth.
Consequence: cheap — a new type is a site-repo change with no engine deploy (ADR-0011), and the content
check command gets its validation rules from the same declarations for free. Expensive — the engine
must treat the type set as data, so nothing may assume a fixed list, and per-type behaviour reachable
only from code (a bespoke View) still needs a template rather than a branch.
Revisit if: a type needs behaviour no declaration can express — then it is a View or an Effect, not a
new field on every type.
Settings cascade
Status: partly adopted → the site level is built as site.yaml (ADR-0039). The section and bundle levels
stay parked: frontmatter covers a bundle, and the trigger for the rest is unchanged — the first section-level
override with a reader.
Deferred because frontmatter alone covers the MVP; a cascade earns itself when a section-wide policy is actually wanted.
Settings cascade: site → section → bundle
Date: 2026-07-28 · Status: accepted
Decision: settings resolve down a cascade — site declaration, then each enclosing section's _index,
then the bundle's own frontmatter — with the nearest explicit value winning. The cascade carries stage
toggles, view selection, taxonomy defaults, cache flags, and metadata defaults; it carries declared
keys only, never arbitrary engine internals. Stages apply to everything by default and are switched off
by a cascade key, not by a predicate compiled into the stage.
Why: stages are mostly no-ops where they do not apply, and their early return is a check on content
shape ("no images here") which is type-independent and belongs in the stage anyway. The cases that really
need control are narrower and cut across types — dithering wrong on one diagram, autolinking wrong in one
poem — which a per-type stage set cannot express and a cascade can. It also unifies with template
selection, which wants the same resolution order.
Consequence: cheap — one resolution rule covers rendering, presentation and metadata defaults; a section
sets a policy once for everything beneath it. Expensive — resolution must be cheap and cached, since it
runs per bundle, and the set of cascadable keys must stay declared or it becomes unbounded config.
Revisit if: cascade resolution shows up in a render-path profile.
Feed shape
Deferred because no feeds exist yet. The tag half of this became ADR-0032 when tags were built.
Recorded direction: /feed.xml carries every type declared primary, /{section}/feed.xml carries a
section, and /tags/{term}/feed.xml falls out of the same Query. Which types are primary is part of the
type declaration, so this and declared types land together.
Extras
Deferred because not in the MVP, and its shape should be discovered by building it.
Extras: local assets, enumerated and browsable
Date: 2026-07-29 · Status: accepted
Decision: a bundle may hold a directory of supporting files — default extras/, named by a cascade key —
which the bundle scanner skips entirely: a .md in there is an asset, never a bundle. The engine
enumerates it as a tree, classifies each entry by extension, renders the ones it can (markdown, plain
text), and serves the rest as bytes behind the ADR-0024 guard. Two behaviours on one route:
…/extras/{path} renders the listing with that entry selected, ?raw returns the bytes. Sorted by
filename; excluded from feeds, queries and search.
Why: drafts, notes and logs are worth publishing as artefacts of the process, and they are not bundles —
no frontmatter, no identity, no language variants. architecture.md already defines a Bundle as carrying
local assets; the only thing missing was enumerating them instead of merely referencing them relatively.
Consequence: cheap — no new primitive, and selecting an entry is an ordinary link, so the whole feature
works without JavaScript. Expensive — the scanner needs an exclusion rule it did not have, and the extras
segment becomes a name no child of a bundle may use, which is why it is a cascade key rather than a
constant.
Revisit if: extras need per-file metadata — and then they are bundles after all, and this entry was wrong.