# Eve integration code survey

Written by **EI.0.01**. The facts in §0.0 of `EVE-V1-REDESIGN-TODOS.md`, each
with the file and line it came from, **re-checked against the tree on
2026-09-19** at `5569b8489e1`.

Abbreviations, as §0.0 uses them: `PC` =
`docs/presentations/presentation-center`, `AD` = `apps/oshun/admin/src`, `B` =
`apps/oshun/bff/src`, `BA` = `B/assistant`, `SA` =
`libs/oshun/shell-assistant/src`.

## What was re-checked, and what moved

Nineteen claims. **Eighteen hold exactly as written.** One does not, and it is
the one a decision rests on — see
[Correction 1](#correction-1-the-bff-does-parse-a-cookie).

## Decks are single files

| Claim                                                                    | Where it is true                                    | Measured                                                                                                                                           |
| ------------------------------------------------------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| The builder inlines `deck.css` and `deck.js` into each deck              | `tools/presentations/build-eve-oshun.py:343-344`    | reads both and interpolates them into the deck HTML                                                                                                |
| `index.html` inlines `center.js`                                         | `build-eve-oshun.py:597` (`render_center`)          | reads `center.css` and `center.js`                                                                                                                 |
| 69 decks                                                                 | `PC/decks/*.html`                                   | **69** files                                                                                                                                       |
| Both scripts are closed IIFEs — no global, no event                      | `PC/deck.js:1`, `PC/center.js:1`                    | both open `(() => {` + `'use strict';`; **0** `window.<name> =` assignments in either                                                              |
| A deck's guide id is `meta.presentationId` in its `#deck-data` block     | `build-eve-oshun.py:678`                            | `deck_meta = {**meta, 'title':…, 'presentationId':entry['id']}` — written by the builder; `deck.js` itself never reads it                          |
| The current slide is the `.slide` without `hidden`                       | `PC/deck.js:4`, `PC/deck.js:179`                    | `querySelectorAll('.slide')`, then `s.hidden = i !== index`                                                                                        |
| `navigate()` uses `history.pushState`, so `hashchange` does not fire     | `PC/deck.js:190`                                    | `history[hashMode === 'replace' ? 'replaceState' : 'pushState'](null, '', hash)` — a `replace` mode exists beside it; neither sets `location.hash` |
| The portal frames a deck as `<iframe id="presentation-frame">`           | `PC/index.html`                                     | the id is present                                                                                                                                  |
| The only cross-frame message is parent → deck `oshun-presentation:pause` | `PC/center.js:124` sends, `PC/deck.js:364` receives | `deck.js` contains **0** `postMessage` calls; `center.js` contains **1**                                                                           |

## The builder-plane dock is the admin chat

| Claim                                                                    | Where                                                        | Measured                                |
| ------------------------------------------------------------------------ | ------------------------------------------------------------ | --------------------------------------- |
| `AD/components/AdminAssistantChat.tsx` is 1,381 lines                    | that file                                                    | **1,381**                               |
| Mounted on every admin page by `AdminAssistantPanel` inside `AdminShell` | `AD/components/AdminShell.tsx:36` (import), `:411` (render)  | both present                            |
| The web `AssistantPanel.tsx` is 7,765 lines with 53 imports              | `apps/oshun/web/src/components/assistant/AssistantPanel.tsx` | **7,765** lines, **53** `^import` lines |

## Auth and the admin origin

| Claim                                                                            | Where                                         | Measured                                                                                                                                       |
| -------------------------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `createAuthPreHandler()` reads `Authorization: Bearer` only                      | `libs/shared/bff-kit/src/authz.ts:99`, `:110` | `authorization.slice('Bearer '.length)`; the only other `cookie` in the file is a comment at `:217`                                            |
| The BFF serves no static files                                                   | `B/**`                                        | **0** files reference `@fastify/static`, `fastifyStatic` or `sendFile`                                                                         |
| `AD/app/api/assistant/**` proxies to the BFF through `AD/lib/admin-bff-proxy.ts` | that file                                     | present                                                                                                                                        |
| Admin's `middleware.ts` refuses every non-public path without the cookie         | `AD/middleware.ts:4-5`, `:18-19`, `:65`       | `PUBLIC_PATHS` = `/unauthorized`, `/handoff`; `PUBLIC_PREFIXES` = `/_next`, `/api`, `/icons`, `/images`, `/favicon`; everything else redirects |
| ~~No cookie is parsed anywhere on the BFF~~                                      | —                                             | **FALSE — see Correction 1**                                                                                                                   |

### Correction 1: the BFF does parse a cookie

§0.0 said, under **The BFF has no browser session**: "no cookie is parsed
anywhere on the BFF". That is not true and was not true when §0.0 was written.

- `B/routes/assistant.ts:676` — `adminAuthContextViaAdminSessionCookie(request)`
  reads `request.headers.cookie`, matches `oshun-admin-session=…`, resolves it
  through `resolveBffAuthToken` and returns an admin `OshunAuthContext`. Its own
  comment (`:659-675`) explains why: EVE-VIS-216, because every member access
  token is hard-coded to `scopes: ['domain:*']` and a real operator on the
  member web could not pass the operator gate. It is used on two READ routes:
  `GET /v1/assistant/catalog-traceability` (`:5084`) and
  `GET /v1/assistant/workbench-board` (`:5113`).
- `B/routes/domain-stubs.ts:1177` — `parseCookies()`, used at `:1243` and
  `:1439` for a **CSRF double-submit token**, not a session.

Dated: `138fc9774ed`, **2026-09-13** — five days before §0.0 was measured.

**Does it overturn decision 1 (the admin console hosts the center)?** No, and
the reason is worth writing down rather than assumed. The BFF still has no
session of its own: it mints nothing, sets no cookie, and the one it reads is
the _admin console's_, accepted only as a second way to prove `admin:` scope and
only when the two are served off one host. The BFF still serves **no** static
files. So the conclusion — the admin origin hosts the center — stands on the two
facts that are still true (admin owns the cookie and the gate; the BFF serves no
files), and the sentence that is not true has been removed from §0.0 rather than
left to be relied on later.

## Page context

| Claim                                                                                       | Where                                      | Measured                                                                                                                                                                |
| ------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BA/page-context.ts` exports `coerceAssistantPageContext` and `buildPageContextPromptBlock` | `:55`, `:102`                              | both found                                                                                                                                                              |
| It accepts five fields and silently drops anything else                                     | `:60-62`, `:64-72`, `:93-97`               | `path`, `title`, `selection` through `cappedString`; `headings` and `anchors` as arrays; the return object is rebuilt field by field, so an unlisted key cannot survive |
| The admin chat sends only `path` and `title`                                                | `AD/components/AdminAssistantChat.tsx:383` | the `pageContext` literal carries those two                                                                                                                             |

## A new tool is invisible until three things change

Confirmed by doing it: ETB.9.01 added `board_next`, `board_show` and
`board_search` and needed exactly these three edits and no others.

| Claim                                                         | Where                                                                                              |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| A binding in a `build…ToolBindings` function                  | `BA/admin-agent-tools.ts`, `B/workbench/workbench-agent-tools.ts`                                  |
| A skill allowlist whose prose is traceable to eval deck cases | `BA/skills/registry.ts:55` (`ASSISTANT_SKILLS`), each skill's `toolAllowlist` and `evalCaseIds`    |
| The prompt ratchet, which freezes serving on a mismatch       | `BA/eve-smx-prompt-hash.ts` (`EVE_APPROVED_PROMPT_BYTES_HASH`), `docs/audits/eve-smx-ratchet.json` |

## Two real ways to enact a change

| Claim                                                                                     | Where                                                                                                      | Measured                                                                                                        |
| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| A 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` | the tool exists; the writer reads that variable and throws `not_configured` without it                          |
| A work item leased by the delegated coding agent                                          | `tools/eve-codex-agent.mjs`, `B/routes/workbench.ts`                                                       | both present                                                                                                    |
| Neither runs a build                                                                      | —                                                                                                          | still true                                                                                                      |
| `B/workbench/artifact-verifier.ts` has no expectation kind that could verify a slide edit | `:213`, `:230`, `:239`, `:251`                                                                             | the kinds are `catalog-change`, `e2e-suite-exists`, `doc-page-exists`, `nodes-exist`. **None is about a slide** |

## Drafts and narration

| Claim                                                                  | Where                                                                                                                             | Measured                                                                                       |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `--draft <id>` renders `PC/drafts/<id>.json` into `PC/.qa-draft-<id>/` | `build-eve-oshun.py:717` (the flag), `:651` (the output prefix), `:731`                                                           | as written                                                                                     |
| Narration goes stale by fingerprint                                    | `tools/presentations/render-eve-oshun-narration.py:70` (`fingerprint`), `:179` (`entry.get('fingerprint') != fingerprint(track)`) | as written                                                                                     |
| 1,712 of 1,721 recordings were made on CPU                             | `PC/narration/manifest.json`                                                                                                      | **1,721** entries, **1,721** `.mp3` files; `device` is `cpu` for **1,712** and `mps` for **9** |

## What does not exist

| Claim                                            | Measured                                                                                                                                                                                                                 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Nothing serves the center over HTTP              | **0** `createServer` in `tools/presentations/*.py` or `*.mjs`                                                                                                                                                            |
| Every center test opens `file://`                | 4 test files reference `file://`; none starts a server                                                                                                                                                                   |
| No store holds a note bound to a page or a slide | no `Presentation`, `Slide` or `Deck` model in `libs/oshun/persistence/prisma/schema.prisma`; no `slideId`/`slide_id` column; the only `*note*` hits in the estate are a rhythm game's lane notes and a Tavus bridge test |
