bdeshi/khosra
0
0
Fork 0
Code Issues Pull Requests Releases Activity

harness: withdraw five pre-code ADRs to deferred ideas

Browse Source 
Twenty-seven ADRs existed before a line of Go. Five specified the shape of
unbuilt mechanisms — cache validity, declared types, the settings cascade,
taxonomies, extras — which breaks the rule against abstraction before a
second concrete use, in prose where the counters cannot see it. They move to
ideas/deferred-decisions.md as recorded intent and return shaped by whatever
implements them.

Citations retargeted throughout; where one was decoration the rule now stands
on its own reasoning. Type declarations and the cascade drop to [spec] with
the MVP behaviour stated instead, so the first prompts have less to build.
conventions.md names http.ServeMux as the router, closing a hole that invited
hand-rolling a path splitter. The ADR gate now checks a number is registered
in the log rather than headed by an entry, so withdrawals resolve and invented
numbers still fail. Two architecture invariants corrected: identity no longer
implies a required language suffix, and the duplicated permalink clause is gone.
This commit is contained in:
bdeshi
2026-08-01 02:23:33 +06:00
parent 54c14a20be
commit 581d6c08ee
13 changed files with 180 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+13 -22
View File
@@ -23,7 +23,7 @@ interactions. Identity is the bundle; language is a variant of it.
## Stage — a transform during rendering
`func(ctx, *Page) error`, in fixed order. Every rendering feature is a Stage: typography, Bengali
numerals, shortcodes, image sizing, dithering. A Stage runs on everything by default and is switched off
by the settings cascade (ADR-0017), never by a type predicate compiled into it; a Stage with nothing to
by a settings cascade key (`ideas/deferred-decisions.md`), never by a type predicate compiled into it; a Stage with nothing to
do returns early on content shape.
**STATUS: deferred.** Called inline in the render path until the transform counter in `state.md`
reaches its threshold. Check it; do not guess.
@@ -72,14 +72,13 @@ extract the resolver when the routing counter in `state.md` is due, not before.
1. **Open page object.** Known fields as struct members plus a `Meta`/`Extra` bag. Absence equals
zero value; templates read what exists and never crash on a missing field. Never add a required
field. Never make a template failure fatal at request time.
2. **Trusted / untrusted pipeline modes.** Content from the site root is trusted; everything else is
not, and
never reaches shortcode or template evaluation. This is the RCE boundary — the one place where an
2. **Trusted / untrusted pipeline modes.** Content from the site root is trusted; everything else is not,
and never reaches shortcode or template evaluation. This is the RCE boundary — the one place where an
extra check beats an elegant unification.
3. **Identity is not language.** `slug.bn.md` / `slug.en.md` with a defined fallback, even while one
language exists. Identity stays stable across translations.
4. **Request-time render behind a cache, fixed permalink policy.** The server shape is the superset;
static export is cache-warming, never a separate code path.
3. **Identity is not language.** The bundle key excludes the language suffix, which is optional for the
default locale (ADR-0021). Identity stays stable across translations.
4. **Request-time render behind a cache.** The server shape is the superset; static export is
cache-warming, never a separate code path.
5. **Permalinks are permanent.** Renames add aliases and redirects. URLs are not reused.
6. **Interactions are off the content graph.** A comment invalidates one fragment, never a build.
7. **Every feature is a leaf** — a View, Stage, Query, Interaction adapter, Effect, or
@@ -95,21 +94,13 @@ extract the resolver when the routing counter in `state.md` is due, not before.
## Re-render and invalidation (target shape, not built)
One validity record per cached entry, five axes, served only while all hold (ADR-0013):
A cached entry needs more than a content-dependency key: time, an engine/template epoch, and an opt-out
all invalidate too. The shape is recorded as intent in `ideas/deferred-decisions.md`; the cache that implements it decides the fields.
| Axis | Invalidated by |
|---|---|
| content deps | bundle keys plus query signatures, taking `old ∪ new` for membership changes |
| interaction fragments | a comment or webmention arriving — the fragment, never the page (invariant 6) |
| `valid-until` | the clock passing the minimum window the render's Stages declared |
| epoch | an engine or template change, which stales every entry at once |
| cacheable | the bundle or route declaring itself uncacheable |
The record maps onto HTTP: ETag from deps plus epoch, `Expires` from `valid-until`, `no-store` for
opt-out — so a proxy in front stays correct without engine code. Stages reach the clock only through an
injected accessor, so a window can never be silently forgotten. Defer the inverted index — v1
re-renders everything, correct until it is slow. Asset derivatives are content-addressed and therefore
immutable: never invalidated, far-future cacheable, a different lifetime from page renders.
Two things hold regardless. Stages reach the clock only through an injected accessor, so a
time-dependent render can never silently outlive its truth. And asset derivatives are content-addressed
and therefore immutable — never invalidated, far-future cacheable, a different lifetime from page
renders. Defer the inverted index: v1 re-renders everything, correct until it is slow.
## Dropped on purpose