Status: Proposed, revision 30, answering the review of Eve revision 3 of this document (2026-09-29) and stating decision 3a as the pipeline carries it out (commit aeceb96dcc1): a repeat that differs moves Dev only while Dev still serves a pair of the renderer build that differed, to the newest stored pair no differing renderer build built, and every pass retries that move until it lands; a new renderer build's first pair is eligible for UAT only once its repeat matched (Elikem, 2026-09-29), so a promotion asked for earlier waits for the repeat without stopping it and UAT never needs a move back; the validation plan tests serving before the repeat; and the time saved is qualified by how releases arrive, with the worst case stated. Revision 29, recording Elikem's decisions of 2026-09-29 on decision 3a: after a Dev release goes live, the next release waits until the publication pipeline has finished one pass, bounded to about an hour ('alternate turns'; measured that day, releases started two minutes apart, the pipeline was stopped seven times and Dev content did not move for twelve hours); and a new renderer build's first pair is served once its checks pass and prepared again afterwards, a repeat that differs moving Dev back to the pair it replaced ('verify after serving'; the blocking repeat had doubled that pass to about 100 minutes). Revision 28, answering the review of Eve revision 13 of this successor: only the pipeline's timer prepares content, so a release or a UAT promotion can stop every preparation and no release waits for one, while content waits visibly instead; and a pair's presentation library must be format 1, every field the slide tool reads present, so a renamed or dropped field or an invalid meta.json is refused. Revision 27, answering the review of Eve revision 8 of this successor: a release preempts a timer preparation, the pointer only moves forward, the contract gate reads the approved scorecard revision from Eve, and a pair's presentation library is checked field by field. Revision 26: decision 6 and its constraint follow Elikem's decision of 2026-09-28 that UAT reads Dev's write-once media in place, without a locked bucket or separate keys. Revision 25, answering the review of Eve revision 3 of this successor: the host runs one preparation or release build at a time and content gets its turn after every release, a pair that goes stale while it is prepared is never pointed to, and every consumer of a pair's files checks their format and fails closed. Revision 24, amending approved revision 23 (Eve revision 60): decisions 3a and 4 follow Elikem's decision of 2026-09-28 that code releases never wait on content; a code release deploys on the served pair and the publication pipeline builds and checks the pair its new code needs. Revision 23: The slide tool's source excerpts come from the pair's own archived sources, derived presentation media is keyed by the renderer that produced it, and the release-time saving is qualified (answering the review of Eve revision 56). Revision 22: A pair-producing code release freezes its own publication at its commit, holds content moves until it deploys and deploys only onto the pointer it built from, and keeps the pair its rollback needs (answering the review of Eve revision 53). Revision 21: Separates the pairs an environment serves (at most its current pair and the one before it) from the pairs kept for other reasons, and makes a renderer-changing release reach UAT only with the pair Dev built for it (answering the review of Eve revision 50). Revision 20: The edge keeps a durable record of the pairs it has applied, so a retained pair keeps serving after a restart without the database, and the ADR states exactly which code releases still run content checks (answering the review of Eve revision 47). Revision 19: The BFF authorizes a pair a request names as the edge does, and every code-owned input of a pair's files (the graph's catalog as well as the renderer) makes a code release build a new pair that deploys together with it (answering the review of Eve revision 44). Revision 18: No file of a pair may depend on when it was built: every recorded time is the publication's freeze time, and the repeat-build check covers every file including the assistant corpora (answering the review of Eve revision 41). Revision 17: Pins the Eve task snapshot the product graph is built from, so a pair's files are the same whenever it is built (answering the review of Eve revision 38). Revision 16: Every file of a pair carries a visibility, so the BFF's and the console's artifacts are never served on public routes, and the console test matches the rule that an open console keeps its pair (answering the review of Eve revision 35). Revision 15: Every content consumer (assistant search, the product graph, the slide tool, the console) follows the served pair or fails closed, answering the reviews of Eve revisions 29 and 32. Revision 14: Phase 1 of the database-driven readers Elikem asked for; on his choice of 2026-09-27 after six review rounds ("Split: phase 1 now"), this ADR decides phase 1 only, and the reader service and search from the database (phases 2 and 3) move to a follow-up ADR, drafted from revision 13 of this one. Revisions 6 to 13 answered independent reviews (pinned renderer inputs including Git history, a record of every served file, pair-scoped URLs, per-host access, retention per pair, an authoritative pointer); what of that phase 1 needs is kept here. Awaiting approval by Elikem; the author does not approve its own ADR.
Date: 2026-09-27
Owner request: Elikem, 2026-09-25: "shouldn't it be more like db driven, fetching content from db when user navigates to that page?" Post-migration item 15. This phase delivers post-migration items 2 (reuse publication builds), 5 (UAT media reuse) and 7 (publication artifact retention).
Related: the Eve content migration ledger (infra/hetzner/eve/content-migration.json); post-migration item 14 (publication tests before shipping); the follow-up ADR for phases 2 and 3 (Eve 5a213aed, a draft carrying this ADR's revision 13).
Pinned sources#
Read at commit ef48257e7f8 of main:
infra/hetzner/platform/publication_release.py:prepareexports the frozen publication, prepares a reader tree, builds the Presentation and Docs Centers, runs the publication test suites, builds the product graph and assistant docs index, runs the browser suites and seals artifacts.infra/hetzner/platform/publication_deployments.py:candidaterebinds the Dev content selection to the release commit;testedis the UAT gate on a Dev-tested publication.infra/hetzner/platform/publication_artifacts.py: sealed static routes; "executable output comes only from the trusted renderer".tools/eve-content/prepare-publication.mjs,tools/render-docs-center.py,tools/presentations/build-eve-oshun.py,tools/eve-content/snapshot-media.mjs.apps/oshun/bff/src/assistant/generated/docs-search-corpus.member.jsonland.full.jsonl: the assistant's two corpora, one per audience (sections of rendered pages with anchors, generated pages and slides); the member corpus is empty andsearch_docsis not offered to members, fail-closed.infra/hetzner/platform/rollout.py: a release mounts one publication's artifacts read-only: into the BFF the assistant corpora (runtime/assistant,OSHUN_ASSISTANT_DOCS_INDEX_DIR), the product graph (runtime/graph,OSHUN_PRODUCT_GRAPH_ARTIFACT_DIR) and the presentation library the slide tool reads; into the admin app the console's presentations and downloads.tools/docs_center/entities.py: entity pages and the portal read each project's creation author and date withgit logat the publication's commit, and yield nothing if Git fails.infra/hetzner/platform/publication_artifacts.py: generated pages, source downloads and archives have separate roots; original content is served as an attachment withX-Content-Type-Options: nosniff, never as a page.tools/docs_center/: besides document revisions the renderer reads tracked files at a commit (gitfiles.py, throughpublication.pyin publication mode) and generates collection and reference pages from them (eve_library.py,glossary.py,domains.py,crates.py,deps.py,coverage.py); every page carries the publication's navigation (article.py:product_nav(manifest, …)).
1. Context#
Eve's PostgreSQL is the source of truth for documents and presentations, but the two readers are still built the way they were when content lived in Git. Every Dev release freezes a publication (the exact approved revision of every document, rebound to the release commit), exports it, rebuilds a file tree of about 5.8 GB from it (documents, the code context at that commit, Git LFS originals), renders it to static HTML with the Python generators, runs the test suites against that tree, and seals the output, which the edge serves as static files. The same run compiles content into code-shaped artifacts: the product graph and the assistant's docs search index.
Measured on release dev-895497ee5adb (2026-09-25):
| Stage | Time |
|---|---|
| Export and reader preparation | 11 min |
| Docs Center render and 188 pytest checks | 14 min |
| Runtime indexes and 242 Docs Center browser checks | 16 min |
| Corpus checks, CMS build and 63 CMS browser checks, sealing | about 30 min |
| Content and publication stages in total | about 70 min of a four-hour release |
The costs this design carries:
- Content cannot go live without a code release. An approved document reaches Dev only when the next release freezes and rebuilds; nothing moves while a release is failing.
- Content and code block each other. A document still in review can stop a code release (the SMX scorecard coupling), and a code change can stale a published walkthrough result, which stops the release until the document is reconciled and approved: result 38 alone stopped five Dev releases on 2026-09-25/26, after three other results had each stopped one on 2026-09-24/25.
- UAT repeats the work. Promotion copies every media object into a separate UAT namespace (14,224 objects, 2.57 GB, about 80 minutes) and rebuilds every image.
- Disk. Each attempt writes a multi-gigabyte reader;
ci/publicationsheld 24 GB and retained failed attempts 83 GB on 2026-09-25.
The static build also gives two guarantees any replacement must keep: readers see exactly the reviewed revisions (UAT serves byte-identical content to what Dev tested), and the tests run against the output readers get.
2. Decision#
The Docs Center and Presentation Center are built once per approved publication, outside the code release, and each environment serves the build its pointer names. Content goes live by moving a pointer, not by rebuilding in a release, and UAT receives exactly what Dev tested by copying the pointer.
- A publication stays an immutable database record of everything its pages are made from: the set of (document, revision, content hash), the code commit its generated pages read, and the digest of its input bundle (decision 1a), under one manifest hash. Freezing, approval rules and the exact-revision guarantee do not change.
1a. Every input the renderer reads is pinned to the publication. At freeze the publication pipeline writes an input bundle: the tracked files the renderer reads at the publication's code commit (what
gitfiles.pyandpublication.pyread today), the collections it generates pages from (the Eve library, glossary, domain registry, crate and dependency references, coverage), and, as data, the commit-scoped Git history it reads (today each project's creation author and date, fromgit logat the publication's commit) and the Eve task snapshot the product graph is built from, captured once at freeze with its capture time and hash recorded in the bundle; and the source snapshots the slide tool quotes, archived from the commits each slide cites (historical ones included); the graph build reads that snapshot and that capture time, never a fresh one or the clock. The bundle is stored content-addressed with its digest in the publication record. The renderer reads only the publication record and its bundle, never its own checkout or Git, and a missing or unreadable bundle input fails the build instead of yielding empty data, so a page's code context is the publication's commit whatever commit the renderer came from. A code release that changes a generated page's inputs freezes a new publication with the same document revisions and the new commit, and a newer task snapshot is taken only by freezing a new publication with the same documents (on the pipeline's schedule, or on demand); each is built and pointed to like any other, so a retry or a promotion always uses the snapshot its publication pinned. No file of a pair may depend on when it was built: any time a generator records in a file (a corpus'sgeneratedAt, a snapshot's capture time, a manifest timestamp) is the publication's freeze time from its record, or is left out, never a file's modification time or the clock, and the build tools run withSOURCE_DATE_EPOCHset to the freeze time. - Each environment points at one validated pair: a publication and the renderer build that built it. A renderer build is the exact code that produces any file of a pair (its commit and the digest of its packaged output): the Docs and Presentation renderers, and the code-owned inputs of the runtime artifacts, such as the catalog the product graph is compiled against, the corpus builder and the presentation library format. The publication pipeline builds one publication with one renderer build, runs the checks (decision 4), and records an eligibility record: the publication id (and so its manifest hash and input bundle digest), the renderer build, and every file the pair serves (decision 3). Dev and UAT each hold a pointer to such a record, never to a publication alone. Publishing an approved selection to Dev moves Dev's pointer to a newly validated pair; promoting to UAT copies Dev's validated pair, so UAT serves byte for byte what Dev tested. Neither needs an image rebuild.
- A pair is served as its own static export, every path scoped to it. The build writes the pair's static export, identified by the pair (not by the publication), and the eligibility record lists every file in it with its digest, content type and response headers: page HTML, the stylesheets, scripts, fonts and images pages load, Markdown source downloads, archives and presentation assets. Original content keeps today's protections (an attachment with
X-Content-Type-Options: nosniff, never served as a page). Every served path is scoped to its pair (/p/<pair>/…), and pages link to their stylesheets, scripts, assets and downloads relatively inside that scope, so a page and everything it loads come from one pair even if the pointer moves between requests; only the entry paths (/, a document's canonical path) redirect to the current pair, and a pair-scoped URL keeps working while its pair is served in that environment (decision 3c). Every file in the record also carries a visibility: public (served on the public hosts), console (served only on the admin-origin console, behind the operator session), or internal (never served over HTTP; read from the pairs directory by the BFF and the admin app). The export keeps the three in separate trees, and the edge maps only the public tree to the public hosts and the public and console trees to the console; the assistant corpora, the product graph and the presentation library are internal, and the console's presentations and downloads are console files, as today's packaging keeps BFF data nonpublic. The edge serves exactly the files of the visibility its host may serve that the record lists, with their recorded headers, and HEAD and byte ranges as it does today (206 withContent-Range, 416 for an unsatisfiable range,Accept-Ranges: bytes); a path the record does not list, or lists with a visibility the host may not serve, answers 404. The renderer stays the trusted one (publication_artifacts.pyrules): content is data, and executable output comes only from the renderer. 3a. A new renderer build serves nothing until it has built and passed; code never waits for it. (Amended by Elikem, 2026-09-28: code releases never wait on content. Measured that day: the renderer build changed in 5 of the last 6 Dev code releases, through the catalog and navigation code the product-graph builder reads and the path mappings intsconfig.base.json, so building a release's pair inside its release would have kept content checks blocking most code releases.) A code release neither selects, checks, prepares nor mounts a publication: it deploys on the pair its environment serves. The publication pipeline runs whenever Dev's current selection, rebound to the live commit, is not the publication of the served pair, which happens after every freeze and every code release: it builds that publication with the live release's renderer build, runs the checks of decision 4 and moves the pointer when the pair passes (decision 3c). A pair that fails keeps no pointer: Dev keeps serving its current pair and the failure is reported to platform-ops. A new renderer build's first pair is prepared a second time after it is served, from the same publication and input bundle, rendering everything again (Elikem, 2026-09-29: 'verify after serving'). The repeat proves the renderer build, not one pair: a renderer build that repeated byte for byte is recorded as proven and builds its later pairs once. Until then the pair of it that Dev serves is repeated after serving, so a repeat a release stopped or the host interrupted runs in a later pass, on that renderer build's pair Dev serves by then; a renderer build Dev stopped serving before its repeat ran is never repeated, and so never reaches UAT (below). Repeats run inside pipeline passes, one pass at a time under the deploy lock, never beside a preparation or another repeat. A repeat that differs in any file marks the renderer build as differing (a later repeat that fails to finish never clears the mark), fails the tested receipt of the pair it repeated, raises a platform-ops alarm, keeps that selection from being prepared again at that commit for four hours (as a failed check does), and moves Dev back. The move back is decided against the pair Dev serves when it runs, not against the pair the first pair replaced: it happens only while Dev's current pair was built by a differing renderer build, and goes to the newest pair Dev was pointed to that is still stored and was built by neither that renderer build nor another whose repeat differed (a renderer build never repeated qualifies: its pair passed its checks and nothing showed it differs). A newer pair of another renderer build that Dev serves by then is never moved back. The move back is an ordinary pointer move (decision 3c): it raises the generation and lands whether or not its target is still in the edge record. The pair a first pair replaced stays in the edge record until the next move, so it is kept at least until then (decision 3b); if no qualifying pair is stored, Dev keeps serving and the alarm says so. Every pass retries a move back that has not landed before it prepares anything. A renderer build whose repeat differed never serves again unrepeated: its next pair is repeated before it is served, within its pass, and a difference fails that preparation. Save for the move back, the pointer only moves forward: one pipeline pass runs at a time, each preparing the selection and commit current when it started, so a pair it finishes is never older than the pair Dev serves; a freeze or a release that arrived during the preparation is prepared by the next pass. One heavy job runs on the Dev host at a time (it has 15 GiB and froze under stacked load), so a preparation and a release's image build never overlap, and code goes first: only the pipeline's timer prepares, and it starts a preparation only while no release runs; no release runs one, in its tail or anywhere else. Content gets one turn after every Dev release (amended by Elikem, 2026-09-29: 'alternate turns'; the day before, releases starting two minutes apart had stopped seven preparations and left Dev content twelve hours behind): once a release goes live, the next release waits until the pipeline has finished one pass at that commit (a pair delivered, a failure, or nothing to do), for at most ten minutes for that pass to start and an hour from its first start. Past that, and for a UAT promotion (selected in Eve or requested by hand) at any time save the repeat it waits for (below), a release stops a running preparation (its whole process tree) and proceeds, asking for the host again rather than queueing behind a preparation the timer starts; the timer prepares that pair again once the host is free. A release never waits on content's state, a check result or a review, and on a preparation at most once, bounded; a repeat after serving holds a release only while a UAT promotion waits for it, at most an hour from the repeat's first start, as a preparation's turn does. The pipeline counts the preparations releases stopped since content was last current and reports them with the waiting selection. Until the new pair is served, Dev shows pages built by the previous renderer build. New code on an older pair, and older code on a newer pair after a code rollback, read only what they can read: every consumer of a pair's files checks their format before using them and fails closed on its own, as decision 7 says: the assistant corpus by its schema version, the product graph by its schema version and by comparing its section hashes with the catalog this BFF compiled, the presentation library by an explicit format. Format 1 is a catalog that declares noformator format 1, every entry with an id, title, summary, href and slide list (a track and a status optional: a deck added in Eve has no track until the catalog assigns one); ameta.json, when present, that is an object with a source revision; and chapters whose every slide has an id, title, subtitle, takeaway, layout, notes, questions and sources (a source being a path or a path with headings), each chapter pinned by its own source revision or by the meta's (the fields the builder always writes, and every Dev library entry carried on 2026-09-28: 69 of 69 catalog entries, 1,721 of 1,721 slides). Any other shape, including a field renamed or dropped while the catalog and chapter lists stay valid, is refused as updating, naming the file and field, rather than read in part or as empty. The console frames the pair's own static Presentation Center, built by the same renderer as the catalog it ships, so it reads no format across versions beyond the guide ids its citation links use, which fall back to an ordinary page load when it cannot read them. A renderer change that changes a format bumps its version or its structure, and a change to the presentation library's fields declares a new format in its catalog, so a mismatched consumer refuses instead of misreading. A code rollback leaves the content pointer where it is: content does not ride with code. A promotion reaches UAT only with a pair Dev built and tested at the promoted commit (the pipeline records that tested pair); Dev and UAT may run different renderer builds, and UAT receives a new one only by promotion of a pair Dev validated with it. A pair whose renderer build has not repeated is not yet validated for UAT (Elikem, 2026-09-29): its tested receipt counts for a promotion only once that renderer build is proven. A promotion asked for while the repeat is pending waits for it and never stops it; the waiting promotion makes that repeat content's turn, so the pipeline runs it at its next pass and a release waits for it as for a preparation, at most an hour from its first start. A promotion of a pair whose repeat differed is refused, its receipt failed. UAT therefore never serves a pair whose renderer build's repeat is pending or differed, and a later mismatch never needs a move back on UAT. 3b. A pair's export is kept as long as anything can serve it. A pointer moves to a pair only when its export is present on the edge host and matches the record's digests. A pair's export is kept while any environment's pointer, rollback pointer (the pair it replaced) or pending promotion names it, or an edge record lists it; keeping an export does not make it served (decision 3c). It is removed only when none of these names it, so neither a renderer upgrade nor an interrupted move removes a pair still in service; pair-scoped URLs of a removed pair answer 404. 3c. One authoritative pointer, which the edge follows. Each environment's pointer is one PostgreSQL row holding (pair, generation); the generation rises by one at every move. A move runs in three steps: (1) prepare: the edge host receives the pair's export under the pair's path and verifies it against the record, without serving it; (2) commit: one transaction moves the row; (3) apply: the edge atomically rewrites its pair file, a durable record of the pairs it has applied (each with its generation), adding the new pair as current, and entry paths redirect to that pair from then on. The record lists at most two pairs, the current one and the one it replaced (the rollback pair); the rewrite that applies a new pair drops the pair before that from the record, even if its export is still kept for a pending promotion or another environment. The edge serves exactly the pairs this record lists and nothing else: a staged pair never enters it, so after a restart, even with PostgreSQL unavailable, the edge still serves a retained earlier pair and still refuses a staged one. Once a pair leaves the record its URLs answer 404 in that environment, whether or not its export is still kept. The edge needs neither PostgreSQL nor any other service to serve. A reconciler, run whenever the edge starts and every minute, compares the pair file with the row: it rolls forward to the committed pair (preparing it if needed) and discards a staged pair the row never committed; if it cannot read the row, the edge keeps serving the pairs its record lists. A new move cannot start until the edge has applied the current one, so at most two pairs (the committed one and the one before it) are ever served in an environment, and both are kept. 3d. A pair-scoped request is authorized three ways. (1) Environment: the pair must be validated for the environment serving it; UAT serves only pairs promoted to it, and a Dev-only pair answers 404 on UAT. (2) Pair state: the pair must be in service there (decision 3c); a staged or pending pair, or one never pointed to, answers 404. (3) Caller: each surface keeps today's rule, and no access changes with this decision. Measured 2026-09-27: the Presentation Center host (presentations.<env>) and the Docs Center (docs.<env>) serve published pages without sign-in; the admin-origin Presentation Center console (admin.<env>/presentations) requires the operator session. A pair-scoped path keeps the rule of the host it is requested on. 3e. The Presentation Center console is bound to one pair. Its entry route resolves the environment's pair once and redirects to the console under that pair's scope; it reads its catalog from that pair's record, not from the file system; the slide it frames uses a URL under the same pair; and its "Ask about this slide" requests carry that pair, so the BFF's slide tool reads that pair's presentation library (decision 7). The BFF authorizes a named pair exactly as the edge does before loading anything from it: the pair must be validated for the BFF's environment and in service there (decision 3d), and the caller must hold the operator session the console requires; a staged, never-pointed-to or other-environment pair, or a caller without the operator session, is refused and, when a request asks for source excerpts, reads them only from that pair's archived source snapshots (decision 1a), verified against the record, never from the BFF's checkout or Git; if the pair or its snapshots are not available to it, it answers that the presentation data is updating rather than reporting the slide missing or answering from another pair. A console opened before a move keeps its pair until reloaded. - Checks move to the publication pipeline, and run for every pair. Link checks, walkthrough-result pins (the publication-marked tests), presentation validators and the reader browser suites run on the export a pair will serve, whenever the pipeline builds a pair (decision 3a). A pair that fails them gets no pointer. Code releases run no content checks: the publication-marked tests run on the pipeline's pair, not on code. Two checks stay, because they concern the code itself: the release preflight checks the commit's route matrix and that an approved scorecard revision measures the commit's model-facing prompt bytes, and the rollout's assistant-contract gate reads that same approved revision from Eve (not from the served pair), so a release that changes the prompt bytes deploys as soon as its measurement is approved, with no freeze.
- Heavy presentation outputs are produced once per input: PDFs, narration audio and screenshots are generated in the background and stored in object storage under a key made of everything that shapes them: the approved content hash, the output generator and renderer build, and the settings used; a pair references only outputs keyed by its own renderer build, so a renderer change regenerates what it affects and the new pair's HTML, PDFs and screenshots always come from the same renderer.
- Media is shared, not copied. (Amended by Elikem, 2026-09-28: no-copy only.) Objects are content-addressed (sha256) and written once: a write succeeds only if the object is absent, and no code path deletes or overwrites one. A UAT publication snapshot reads the Dev objects its publication pins in place, instead of copying them into a UAT namespace; UAT's content service is read-only and serves only media its snapshot database lists, which are exactly the publication's pinned media. Promotion proves every pinned object present in both its primary and recovery copies at its recorded size by listing the store, and re-hashes a sample (measured: 14,228 objects, 2.57 GB, in 4 seconds, where the copy took about 80 minutes). The isolation this keeps is set out in section 6.
- Every content consumer in the BFF and the admin app follows the served pair, or fails closed. Today a release mounts one publication's artifacts into them (see pinned sources). In this phase each pair's build produces those artifacts too, as files of the pair's export listed in its record and checked with it: the assistant corpora (one per audience), the product graph, the presentation library, and the console's presentations and downloads. The BFF and the admin app mount the environment's pairs directory read-only instead of one publication's artifacts, read the environment's pair file (the one the edge follows), load that pair's artifacts, and reload when the pair file changes, including a rollback to the previous pair. Assistant search and the citations it returns come from the loaded pair and link into its scoped URLs; graph-backed answers read that pair's graph; the slide tool reads the pair a request names (decision 3e) or else the pair file's. A consumer that has not yet loaded, or cannot verify, the pair its pair file names does not answer from anything else:
search_docsis not offered, graph-backed tools and the slide tool answer that their data is updating. Signed-out Docs Center search stays client-side over the pair's own public index. Search from PostgreSQL and a shared retrieval service remain phase 3, in the follow-up ADR.
3. Alternatives considered#
- Keep the static build per release (today). Rejected for the costs above: about 70 minutes of every release, content gated on code releases, and a full UAT rebuild and copy.
- A reader service rendering or serving from the database, and search from PostgreSQL (phases 2 and 3). Deferred to the follow-up ADR: it adds a runtime service, a multi-consumer pointer protocol and retrieval rules that six review rounds are still refining, while phase 1 alone removes the per-release rebuild, the UAT rebuild and copy, and the content-code coupling.
- Render in the browser from an API. Rejected: it moves the trusted renderer into untrusted clients, weakens the content-is-data rule, and hurts first paint and accessibility.
4. Plan#
- Phase 1 (this ADR). Move
prepareout of the Dev release into a publication pipeline triggered by a freeze or by a code release going live: write the input bundle, build and check the pair, store its export and eligibility record by pair, and move the pointer (decision 3c). Releases and promotions reference pairs. Media moves to shared content-addressed storage with environment read grants. Reversible to today's per-release build. - Validation plan: a pair move followed by the slide tool asked for source excerpts, including a source pinned to a historical commit, answering from the new pair's archived snapshots with no checkout present; a renderer-only change, whose new pair's PDFs and screenshots are regenerated and match its HTML; a code release that changes only a generated page's code input, whose new pair reflects the new commit; a code release that changes a pair's code input, after which Dev serves its older pair until the pipeline's new pair passes and is pointed to, with graph requests refused meanwhile only if the catalog changed; a code rollback, which leaves the content pointer where it is; a freeze and a release each landing while a pair is prepared, after which that pair is pointed to (it is newer than the served one) and the next pass prepares and serves the current selection; two releases arriving in succession while the pipeline prepares the pair the first one needs after it went live, the second stopping that preparation and deploying at once, and the pair prepared once the host is free, with the stopped preparations reported meanwhile; a UAT promotion requested during a preparation, which stops it and proceeds; a new renderer build's first pair served as soon as its checks pass and repeated afterwards, the renderer build recorded as proven when the repeat matches and its later pairs built once; a repeat that differs, after which the pair's tested receipt fails, the platform-ops alarm opens and Dev moves to the newest stored pair no differing renderer build built, and that renderer build's next pair is repeated before it is served; a repeat that differs after Dev has moved on to a pair of another renderer build, which leaves Dev on that newer pair; a move back that fails, retried by the next pass before it prepares anything; a differing repeat with no qualifying stored pair, after which Dev keeps serving and the alarm says so; a repeat stopped by a release and one the host interrupted, each run by a later pass on the pair Dev then serves, the second never clearing an earlier difference; a UAT promotion requested while a first pair's repeat is pending, which waits for it without stopping it, holds a release for at most an hour from the repeat's first start, and proceeds when the repeat matches or is refused when it differs; new code on an older pair and older code on a newer pair with a changed corpus, graph and library format, each consumer refusing on its own; a pair-served library whose slides' sources field is renamed, whose catalog entries lack a summary, whose catalog declares format 2, or whose
meta.jsonis not an object, each refused while the catalog and chapter lists stay valid; moves A to B to C while A is kept for a pending promotion, after which the edge record lists only C and B and A's URLs answer 404 while its export remains; a renderer-changing release with Dev and UAT on different publications, whose promotion moves UAT to the pair Dev built for it; after a move from pair A to B, restarting the edge with PostgreSQL unavailable, a retained A page and its assets still serve and a staged pair still answers 404; a code release passing with a stale published result and content in review present; slide-tool requests naming a forged staged, never-pointed-to or Dev-only pair (on UAT), and one without an operator session, each refused by the BFF; a code release that changes only the graph's catalog, whose pair the pipeline builds after it goes live and whose graph requests are answered once that pair is served; rebuilding the same pair after time passes and after task data changes, giving identical digests for every file including the product graph and the assistant corpora, and a new snapshot giving a new publication and pair; content-only pointer moves and a rollback while the BFF and admin app run, after each of which assistant search and its citations, graph-backed answers and the slide tool answer from the pair the pair file names (a new slide found, a revised slide answered from its new text, from a console opened after the move; a console opened before the move keeps displaying and answering from its original pair until reloaded, selects the new pair and its revised slide once reloaded, and answers that the presentation data is updating if its original pair is no longer available); a pair whose search, graph or presentation artifacts are missing or corrupt, for which each consumer fails closed as decision 7 says; tests that the edge serves only files a pair's record lists with a visibility its host may serve (a path outside the record, and direct requests for internal files such as the corpora, the graph and the presentation library, or for console files on the public hosts, answer 404), with their recorded headers; downloads as attachments withnosniff; HEAD and satisfiable and unsatisfiable byte ranges for presentation audio and PDFs; an unchanged revision reused in a new publication served with the new publication's navigation; the same publication built by renderer builds packaged from two other checkouts, without the publication's Git history, giving identical output, and a build with the bundle's Git history removed failing; a renderer upgrade producing a new pair while the old one's export stays until nothing names it; the authorization rules of decision 3d on both presentation surfaces with and without an operator session, and for staged and Dev-only pairs; the console test of decision 3e (a pointer move between loading the console and its framed slide keeps the console's pair); failpoint tests that stop a move after prepare, after commit and after apply, and a second move attempted before the edge applied the first, each followed by the reconciler bringing the edge to the committed pair; and an outage drill (stop PostgreSQL and the object store on Dev: the edge keeps serving its pair from local exports).
5. Consequences#
Gains
- Up to about an hour off the path from a merge to live Dev code, depending on how releases arrive: no Dev code release prepares or checks content. A release that finds content's turn already served (a pipeline pass finished since the last release went live) saves the whole content stage, about 70 minutes of a four-hour release (measured above). A release that arrives during content's turn waits for it, at most ten minutes for the pass to start and an hour from its first start, and then stops any preparation it finds (decision 3a); its worst case, about 70 minutes, saves nothing over today's content stage. While a UAT promotion waits for a new renderer build's repeat, a release can wait up to another hour for that repeat. Phase 1 reports the measured times and how often releases waited. The host's work per release is about the same; what changes is that a content failure never stops code and content no longer needs a code release. The cost is shared: content lands after every release, and a merge that arrives meanwhile waits up to about 70 minutes for it; Dev serves its previous pair meanwhile (after a code release that changed a format, the affected consumer answers that its data is updating), and the pipeline's status shows the waiting selection and how many preparations releases stopped. Phase 1 reports the measured times. No image rebuild or media copy on UAT promotion.
- Approved content reaches Dev without a code release; a failing code release no longer holds content back; and content in review, a stale published result or a failing pair no longer stops any code release. After a release that changes a pair's code, Dev serves its previous pair, with graph answers refused if the catalog changed, until the pipeline's new pair passes and is pointed to; a pair that fails leaves Dev on the previous one until its content is fixed. A release that changes the model-facing prompt bytes deploys once its measurement is approved in Eve (decision 4); no freeze is needed.
- Disk: no per-release reader tree; artifacts are kept per pair still in use, not per attempt.
- Post-migration items 2, 5 and 7 are delivered.
Costs and risks
- Storage per pair. A pair's export is kept until nothing names it: per environment at most the current pair and its rollback pair are served, and a pending promotion can keep one more (unserved), on the edge host and in object storage. Phase 1 measures the size of one pair and sets the retention bound from it.
- Every publication builds every page. A document change builds the whole publication (its navigation reaches every page), as today, but no longer waits for a code release.
- About 430 Docs and Presentation checks (188 pytest, 242 browser) move from the release to the publication pipeline, which must fail loudly and block the pointer.
- A new renderer build reaches UAT later. Its first pair is promotable only once its repeat matched, about one more preparation's time (47 to 57 minutes measured on 2026-09-29) after Dev serves it; later pairs of a proven renderer build are promotable as soon as they are served.
- Pointers to govern. Moving an environment's pointer becomes the publish action for content; it needs the same audit trail and the tested-publication rule for UAT that promotion has today.
6. Constraints proposed for approval#
- UAT isolation from Dev writes. Media objects are write-once and content-addressed in the application: a write names the object by its hash and succeeds only if it is absent, and no code path deletes or overwrites one, so an object UAT reads cannot change under it. The store itself does not enforce this: Dev, UAT and the off-box backups share one bucket and one key pair, the bucket has no object lock or versioning, and object lock can only be enabled on a new bucket. Elikem chose on 2026-09-28 not to add a locked bucket, deletion holds or separate keys. If a regulator requires UAT media in separate storage, one configuration value restores today's per-promotion copy.
- Behaviour during an outage. The edge serves its pair file's pair from exports on its own disk, so a PostgreSQL or object-store outage does not stop the readers; a file missing from the export answers 404 as it would at any time, and a missing export answers 503 with a maintenance message. No page is ever served from an unvalidated or staged pair.