Eve library

Four surfaces: the architecture of Eve inside the Presentation Center

Guide

Revision 2

On this page

Written by EI.0.02. The five decisions of §0.0 of EVE-V1-REDESIGN-TODOS.md, what each one rejected, what the rejected road would have cost — measured, not estimated — and, for each decision, the file that changes if it is reversed.

Measured on 2026-09-19 at cee74e22d75. The facts the decisions rest on are re-checked in eve-integration-code-survey-2026-09-18.md, which also records the one claim that turned out to be false.

Decision 6 was added by EI.8.00 later the same day, measured at c119736ec3a, after the backlog audit found that decision 4 had been written for one machine and the deployed stack is another.

Decision 7 was added by EI.0.11, measured at 062dd705114, after EI.0.03 found that two of the four threat-model rows it was asked for could not be written truthfully — one because the surface belongs to another application, and one because the code it would describe does not exist yet.

Abbreviations: PC = docs/presentations/presentation-center, AD = apps/oshun/admin/src, B = apps/oshun/bff/src, BA = B/assistant.


The seven decisions#

1. The admin console hosts the center#

The center stays a generated static site; the admin origin serves its published files read-only and shows them in a frame.

Rejected: the BFF hosts it. §12.3 of TODOS.md recommended the BFF because "a same-origin page needs no cross-origin session plumbing". The BFF has no session of its own to be same-origin with, and the admin origin already has the operator cookie, the assistant proxy routes (AD/app/api/assistant/** through AD/lib/admin-bff-proxy.ts) and the gate (AD/middleware.ts, which lets through only /unauthorized, /handoff, /_next, /api, /icons, /images and /favicon).

Measured cost of the rejected road:

What it would need Measured
A static-file plugin @fastify/static is not in the pnpm catalog. The catalog holds exactly two @fastify/* entries — @fastify/cors and @fastify/multipart (pnpm-workspace.yaml:150-151) — so this is a new catalog entry plus a new BFF dependency
A cookie session The BFF sets no cookie anywhere. It reads one (see the survey's Correction 1) but mints none, so a session means a new plugin or a hand-rolled store
A CSRF regime The only one on the BFF is the double-submit pair in B/routes/domain-stubs.ts — oshun-csrf + x-csrf-token, 32 random bytes, an 8-hour cookie, its own parseCookies, an origin guard and a non-browser exemption: 19 CSRF references in that one file
Threat-model rows A browser session on the BFF is a new boundary, so a new plane. The model holds 12 planes, 11 classes and 75 cells; workbench-intent alone carries 7 capability claims and 10 cells. Each cell needs a disposition and named controls, and threat-model.spec.ts refuses an unowned one

Reverse it by changing: AD/app/… (the wrapper route that frames the center) and AD/lib/presentation-center-files.ts — the resolver EI.1.01 adds. A reversal moves both to B/routes/ and adds the four rows above.

2. Eve is the existing admin chat, not a bundled island#

The wrapper page sits inside AdminShell, so the dock already mounted there is the dock. The static pages gain a message contract, not a script tag; read from file:// they behave exactly as before.

Rejected: a standalone esbuild island of the admin chat. It is not impossible — tools/presentations/tests/eve-operator-chat-capture.mjs bundles AdminAssistantChat today with bundlePinned (esbuild, bundle: true, format: 'iife') and only three mocked module boundaries: next/navigation, next/link and @/lib/admin-voice.

Measured cost: the island would be a second copy of a 1,381-line component to keep in step with the first, plus those three substitutions maintained as the component grows. The capture exists to photograph the chat, not to ship it; making it a delivery path makes every future edit to AD/components/AdminAssistantChat.tsx a two-place edit.

Also rejected: the web dock. apps/oshun/web/src/components/assistant/AssistantPanel.tsx is 7,765 lines with 53 imports, and three of them are the member plane itself: useAuth from @/lib/auth-context (line 140), the library store (line 148) and the profile and preferences stores (line 174). It is the member dock; it is not a candidate.

Reverse it by changing: tools/presentations/tests/pinned-bundle.mjs would become a build step rather than a test helper, and PC/deck.js / PC/center.js would gain the script tag this decision keeps out of them.

3. The page sends identifiers; the server reads the slide#

The browser is untrusted, so page context carries the guide id, the slide id and a short visible excerpt, and Eve reads titles, notes, sources and excerpts through a read tool over the canonical PC/content/*.json in the checkout.

Rejected: the page sends the slide text. The context path already drops what it is not told to keep: BA/page-context.ts accepts exactly five fields — path, title, headings, anchors, selection (:55, :102) — and rebuilds its return object field by field, so an unlisted key cannot survive. Sending slide bodies would mean widening that contract for the one surface that is easiest to forge, and the model would be reading page-supplied prose as if it were the repository's.

The identifiers are already there to send: a deck's guide id is meta.presentationId in its #deck-data block, written by the builder at tools/presentations/build-eve-oshun.py:678, and the current slide is the one .slide without hidden (PC/deck.js:4, :179).

Reverse it by changing: BA/page-context.ts — a sixth field, and the coerceAssistantPageContext contract that today refuses one.

4. Small edits are written directly; structural ones go to the work queue#

Text, notes and takeaway edits to existing slides use the confirm-gated write path with a draft preview first. Adding, removing or reordering slides, changing a layout or a diagram goes through a work item.

The two enactment paths both exist already: the confirm-gated atomic write into OSHUN_WORKBENCH_REPO_DIR (B/workbench/workbench-agent-tools.ts:773 export_decision_adr → B/workbench/decision-adr-file.ts:54), and a work item leased by the delegated coding agent (tools/eve-codex-agent.mjs, B/routes/workbench.ts). The draft preview exists too: build-eve-oshun.py --draft <id> (:717) renders PC/drafts/<id>.json into PC/.qa-draft-<id>/ (:651) with every validator applied and without touching the library. Amended 2026-09-21 (EI.8.01, EI.8.02): that command renders a manuscript at the library pin; a change is previewed by tools/presentations/eve_change.py preview, which reads each replaced slide at its own chapter's pin, and its draft format is authoring/eve-change-drafts.md.

Rejected: everything through the work queue. It would be safe and unusable — a typo fix would wait for a lease. Rejected: everything written directly. Nothing could then verify it: B/workbench/artifact-verifier.ts has exactly four expectation kinds — catalog-change (:213), e2e-suite-exists (:230), doc-page-exists (:239) and nodes-exist (:251) — and none is about a slide, so structural work could never reach verified. That is why this decision owes the verifier a presentation-slides kind.

Reverse it by changing: B/workbench/artifact-verifier.ts — the boundary between the two paths is exactly the set of expectation kinds it can check.

5. Operators only#

The center teaches engineering internals. Every route and tool in this phase requires the admin: scope; the member corpus stays empty.

Rejected: members see the center. The member corpus is empty by decision and by measurement: ./eve docs export --format bff-corpus --scope member emits a meta line and zero chunks, which is what makes loadAssistantDocsSearch fail closed and never offer search_docs at all (ETB.8.10; BA/docs-search.ts). docs-search-member-audience.spec.ts guards it against the checked-in artifact, because the rule that once filled it admitted 317 engineering pages to members.

Reverse it by changing: BA/skills/registry.ts — the skill whose toolAllowlist names these tools, and the authScopes on the eval deck cases that hold its prose to measurement.

6. Authoring runs where the checkout is#

Owner decision, 19 September 2026: proposing, previewing, applying and reverting a change to the library is a local-operator capability. It works on a machine that has the repository, the builder's Python and, for narration, the Kokoro environment. The deployed stack has none of them, answers not_configured, and the console says so. Nothing in 0.9–0.12 claims more.

Decision 4 writes into OSHUN_WORKBENCH_REPO_DIR and 0.9–0.10 run Python beside the BFF. On a developer machine both exist. In the deployed stack:

  • The BFF image is Node on Alpine (docker/Dockerfile.node:28) and adds exactly one package for the BFF, ffmpeg (:136). There is no Python in it.
  • The BFF service sets neither OSHUN_WORKBENCH_REPO_DIR nor OSHUN_PRESENTATIONS_PYTHON (infra/hetzner/docker-compose.yml:322-449), its only volume is its run state (:430-431), and its memory limit is 512 MiB (:334).
  • Admin mounts the published center read-only (:576), filled once per deploy by infra/hetzner/scripts/deploy.sh:238 from a staging copy with EI.1.02's allowlist. A preview or an applied change written by the BFF is not a file admin can serve.

So the resolution the write path already uses is the whole mechanism: B/workbench/decision-adr-file.ts:54 and BA/presentation-library.ts:92 read OSHUN_WORKBENCH_REPO_DIR (or walk up to the workspace root) and throw a typed not_configured when there is none, and EI.8.03's runner has no default for OSHUN_PRESENTATIONS_PYTHON. Where those resolve, authoring works; where they do not, it refuses in those words.

What EI.8.05's preview handler reads from. On an operator machine, the .qa-draft-eve-<changeId>/ directory under the same checkout, which admin resolves from OSHUN_PRESENTATION_CENTER_DIR or by walking up to the workspace root (AD/lib/presentation-center-files.ts:82). In the deployed stack there is no draft to serve: no proposal can have been made, so the handler answers 404 like any unknown change, and never 503 for a preview that was claimed.

The same fact reaches the read side, and it is cheaper to fix. The read loader of EI.5.01 needs the library's source too, so today a deployed Eve answers not_configured to "what supports this slide's claim" as well. Reads need no Python and no writable tree: the deploy already copies the center's source to the host (.github/workflows/deploy-hetzner.yml:417), and a read-only mount of it into the BFF is enough. That is EI.5.06. Source excerpts at a pinned revision (EI.5.02) need git, and stay local.

Rejected: a deployed authoring worker. It is the right shape for several operators and the wrong cost for one. Counted against the code: a second image with Python and the builder, Chromium for the PDF step, and kokoro, torch, numpy, soundfile and huggingface_hub for narration (tools/presentations/render-eve-oshun-narration.py:5); a writable checkout the worker owns, where the BFF has only a run-state volume; a publish step from that checkout into the mount admin reads, which today only deploy.sh writes; a lock that holds across processes, where EI.9.02's holds inside one; recovery after a crash between the content write, the receipt row (EI.9.03) and the publish; and a way for an applied change to get back into git, because EI.9.08 leaves the commit to a person and a deployed checkout has nobody at it. The verification supervisor refuses to start with less than 3 GiB available (tools/presentations/run-supervised.py:55) on a stack budgeted at 6.5 GiB in total (docker-compose.yml:36). The one operator there is already has a machine where all of this exists.

Reverse it by changing: infra/hetzner/docker-compose.yml — a worker service with a writable checkout volume and the two variables — and BA/presentation-builder-runner.ts (EI.8.03), which would dispatch to that worker instead of spawning a subprocess. The tools, the draft format, the receipt and the confirm cards do not change: they talk to the runner, not to Python.

7. The framed center is the admin app's surface, not a plane of Eve's model#

BA/security/threat-model.ts is not widened to carry the framed Presentation Center. What crosses from that frame INTO Eve is already modelled; the page itself — same-origin static HTML with inline script inside the console — is the admin app's surface, and is held by admin-app controls that already exist.

The model is the assistant's, and its own contents say so. Measured 2026-09-19: every plane in it cites only apps/oshun/bff files — a grep for apps/oshun/admin returns zero — and ThreatPlane requires each plane to name the assistant routes, agent tools and model legs it owns, which threat-model-inventory.ts cross-checks against what the BFF runtime actually registers (CoverageReport.routesClaimed / toolsClaimed / legsClaimed). A static-file route in another app owns none of the three.

What already carries the parts that do reach Eve. The slide text and source excerpts are the presentation-content plane with its four cells, seam and result label (EI.0.03). The identifiers the page posts ride in page-context, which is declared untrusted and, since EI.4.03, framed on the wire; EI.4.04 drops them for anyone without admin scope.

What holds the front-end surface, with the code that does it. The published files answer under a scoped policy — script-src 'self' 'unsafe-inline', frame-src 'self', frame-ancestors 'self' and, the part worth having, connect-src 'none', so a deck that gained a fetch is refused by the browser rather than by review (AD/next.config.mjs, PRESENTATION_FILES_CSP). Only an allowlist of published paths is served at all (AD/lib/presentation-center-files.ts, PUBLISHED_FILES / PUBLISHED_TREES). Both ends of the postMessage contract check the origin and the sending window (PC/deck.js, PC/center.js), and every message goes through a parser that refuses rather than repairs (SA/presentation-messages.ts, parsePresentationMessage).

Rejected: widen the BFF model to cite admin files. The evidence check would pass — it reads any repository path — and everything else would stop being true. The plane would declare no route, no tool and no model leg, so the inventory would carry a plane it cannot verify against a runtime; PLANE_SEAM (BA/security/red-team-matrix.ts) places every plane on the prompt, tool or runtime seam of a TURN, and a static-file route sits on none of them; and the model's opening sentence — a place where data or authority crosses a boundary of the assistant — would stop describing its own contents. The cost is not the edit; it is that the model stops meaning one thing.

Deferred, not rejected: a threat model of the admin app's own. That is the right home, and it is a new artifact — its own classes, its own applicability rule, its own cells and spec — for a surface already held by the four controls above. It is named here so the next admin surface that needs one knows where it goes, rather than being discovered again.

Reverse it by changing: BA/security/threat-model.ts (the plane and its cells), BA/security/red-team-matrix.ts (PLANE_SEAM) and BA/security/trust-labels.ts (PLANE_RESULT_TRUST) — or, for the deferred answer, a new apps/oshun/admin/src/security/threat-model.ts with a spec of its own. Nothing in 0.1–0.7 changes either way: no tool, route or prompt part depends on where this surface is written down.


What stays from §12 of TODOS.md#

§12 opens with the owner's decision of 11 September 2026: the Presentation Center and the Docs Center stay generated static sites, are not rewritten as React applications and do not gain a CMS. Three properties are named there as the ones to preserve, and this phase preserves all three:

  • Static generators. build-eve-oshun.py still renders the whole library: 69 single-file decks with deck.css and deck.js inlined (:343-344) and an index.html with center.js inlined (:597). Nothing in Phase 0 makes a deck depend on a server.
  • A deterministic --check. build-eve-oshun.py --check (:714) still renders and compares rather than trusting the tree, and --draft keeps a preview out of the library entirely.
  • Offline reading. Both bundles are closed IIFEs — (() => { 'use strict'; at PC/deck.js:1 and PC/center.js:1, with zero window.<name> = assignments in either — and the only cross-frame message is parent → deck oshun-presentation:pause (PC/center.js:124 sends, PC/deck.js:364 receives; deck.js sends none). A deck opened from file:// behaves exactly as it does inside the console, because the contract it gains is a message it may never receive.

The reversal table#

Decision Reverse it by changing
1. The admin console hosts the center AD/lib/presentation-center-files.ts and the AD/app/… wrapper route
2. Eve is the existing admin chat tools/presentations/tests/pinned-bundle.mjs (test helper → build step) and PC/deck.js / PC/center.js
3. The page sends identifiers BA/page-context.ts
4. Small edits direct, structural queued B/workbench/artifact-verifier.ts
5. Operators only BA/skills/registry.ts
6. Authoring runs where the checkout is infra/hetzner/docker-compose.yml (a worker with a writable checkout) and BA/presentation-builder-runner.ts
7. The framed center is admin's surface BA/security/threat-model.ts, BA/security/red-team-matrix.ts and BA/security/trust-labels.ts — or a new admin-app model