bdeshiandClaude Opus 5
9349c54d2e
Addresses like /.well-known/security.txt are fixed by somebody else's spec. None is a bundle, none belongs under /static/, and core had no way to serve one. This is the trigger the extension registry has been held for, in those words: ADR-0042 called core's generic derived-file route "the seam to revisit when a second feature wants output of its own", and state.md's counter note said to build the registry "when a feature wants a route". Raw passthrough is that feature, so the seam is built rather than worked around. Only Routes, not the seven-field Extension struct extensions.md describes. Five of the other six fields have no implementor and building them would be the speculation rule 6 forbids. It also kept the change inside the core budget, which had 65 lines left: the seam is ~30 core lines and the feature's own code lands in internal/ext/, where there is room. Core is 2965/3000. A feature returns map[string]http.Handler; core mounts each as an exact pattern and learns nothing about who owns it. A path core already answers is skipped with a warning, not overridden — http.ServeMux panics on a duplicate pattern, so a site shipping root/robots.txt would otherwise take the server down at startup. Verified: server alive, engine keeps /robots.txt, warning logged, zero panics. Templating is opt-in by filename. A .tmpl suffix is stripped from the URL and the file is rendered with text/template — never html/template, which would turn an ampersand in a contact address into & and a JSON quote into ". Opt-in by name rather than by sniffing the type, because a key or a signature may contain anything and a pass choosing for itself which files to rewrite would eventually eat one. The data is the site's own declarations and nothing more, which is the point: a security.txt naming its canonical URL should not repeat what site.yaml already says. Headers come from root/_headers.yaml, exact paths only. Globs are a second-use feature and the concrete need is a handful of .well-known names. The manifest is not served, by the leading-underscore rule that already means "not addressable" everywhere else — no special case was added for it. A manifest that will not parse is logged and ignored; the files still serve. Found while counting: the Extensions row read 4 while five packages existed. notation landed in ADR-0061/0062 and was never counted, though the prose beside the number already named all five. Corrected to 6. That is the latent item about counters having no mechanical check, demonstrating itself. Not done, and logged as latent: khosra check cannot report a root/ file shadowing an engine path, because verify.sh fails a feature that imports a sibling and the reserved paths live in passthrough. The startup warning fires on every boot, which is louder than a check finding. Evidence against the demo with a fresh binary: /pubkey answers with its declared text/plain despite having no extension; /.well-known/security.txt answers with Canonical filled from site.yaml's base, plus the declared CORS header; /humans.txt gets a derived type; /_headers.yaml is 404; / and a bundle page are untouched. Eight unit tests cover layout, absence, interpolation, non-escaping, declared and derived headers, a broken template, and a broken manifest. 24 files, +514/-46. Extensions 4 (miscounted) → 6. Routing cases unmoved: exact paths are mux entries, not resolver cases. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
examples/
demo-site/ is a complete khosra site, kept here to be read and served — the demonstration a person walks
through to see what the engine does, and the fixture the engine tests itself against (ADR-0051).
make demo # serves it at localhost:8080
khosra check -site examples/demo-site
It is content, not a fixture in disguise: every file is what an author would write. Two things keep it honest,
both in verify.sh:
TestTheExampleSiteExercisesEveryFeature(ininternal/web) serves this directory through the real handler and asserts one case per feature. A feature that changes shape breaks it.khosra checkruns over it and must report nothing fatal.
Adding a feature means adding it here, with a case in that test. A feature the example does not show is a feature nobody can see working, and the gates are what stop that from being optional.
What each part is for
| Path | Demonstrates |
|---|---|
site.yaml |
the two site-level settings: base and title |
content/posts/day-01…11 |
pagination — eleven dated posts against a page size of ten |
content/posts/first-light/ |
two languages, a directory bundle owning a picture, a figure with a caption |
content/posts/only-english |
the fallback chain, and a canonical link naming the variant actually served |
content/posts/renamed-thing/ |
slug moving an address, aliases keeping the old one working |
content/posts/unfinished |
a draft: invisible without -dev on |
content/posts/scheduled |
a future date: published by the clock, with nothing to run |
content/comics/the-long-monsoon/ |
a series — structural membership, sparse order, prev/next/first/last, an archive, and a landing page in two languages |
content/art/monsoon-studies/ |
a gallery: three JPEGs sized into a srcset, and an SVG left exactly as drawn |
content/writing/notes-on-water/ |
an include whose fragment has no URL, and an extras/ tree with a nested directory |
content/writing/typography |
what the engine does to prose, and what it deliberately does not |
content/pages/* |
undated bundles: reachable, and absent from every feed |
content/pages/bengali-only |
a bundle that exists in one non-default language only |
content/status/* |
a titleless bundle — legal, and the one check warning this site expects |
templates/list.html |
overriding a single named block and inheriting the document |
static/note.txt |
files served verbatim |
The one expected warning
khosra check reports the titleless status note. That is deliberate: titleless is legal, the theme falls back
to the bundle's key, and the warning exists so an author who did not mean it finds out. A fatal finding here
would fail verify.sh.