Eve library

Eve change drafts

Guide

Revision 2

On this page

Written by EI.8.02, on 21 September 2026. The format of a change Eve proposes to a slide that already exists, from the moment it is proposed until it is applied or discarded. It is read by the runner (tools/presentations/eve_change.py, EI.8.01), written by the proposal tool (EI.8.04), shown by the preview route and the card (EI.8.05, EI.8.06) and re-hashed by apply (EI.9.01).

Abbreviations, as §0.0 of EVE-V1-REDESIGN-TODOS.md uses them: PC = docs/presentations/presentation-center, BA = apps/oshun/bff/src/assistant.

Where it lives#

PC/drafts/eve-<changeId>.json, where the change id is a lowercase UUID as crypto.randomUUID() writes one. Its preview is PC/.qa-draft-eve-<changeId>/.

Why a UUID and not any name. The same directory holds reviewed manuscripts, twenty of them named eve-… on 21 September 2026 (eve-charter-chapter.json and its siblings). A change id of any other shape could collide with one, and the runner would then treat a manuscript as a change. The runner reads only a UUID-shaped name, and .gitignore ignores only that shape.

Never staged. A draft is a working file. When a change is applied, a person commits the chapter files it wrote (EI.9.08). The proposal does not go in with them. .gitignore carries the pattern, so git status does not offer it.

The fields#

Field Required What it holds
sourceRevision yes The library's pin, meta.json sourceRevision. A draft made against another pin is refused.
title yes The title of the preview deck, for example "Proposed change to Where each track begins".
subtitle no The preview deck's subtitle.
slides yes One or more complete replacement slide objects. Each has the id of a library slide and is written exactly as its chapter file will hold it.
basedOn yes Slide id → sha256 of the library slide it replaces, taken when the change was proposed. It names exactly the replaced slides.
proposedBy yes {operatorSub, tenantId}: who proposed it. It stays the record until the receipt row exists (EI.9.03), and EI.8.05 and EI.8.06 ask for it first.
createdAt yes When it was proposed, as Date.prototype.toISOString() writes it: 2026-09-21T12:00:00.000Z. The form without milliseconds is also accepted.
reason no Why the change was proposed, in a sentence; the proposal tool (EI.8.04) always writes it, and the card shows it.

No other key is read. The builder does not read basedOn, proposedBy, createdAt or reason, and none of them reaches a rendered deck, its coverage or its narration script. test_build.py checks that for build_draft, and test_eve_change.py checks it for the preview.

A replacement slide does not carry sourceRevision, deckContext, chapter or release unless its chapter file already does. The runner attaches the chapter's own pin and chapter, as the builder does when it loads the library.

json
{
  "title": "Proposed change to Where each track begins",
  "sourceRevision": "1ceae52c7896a59ac74a4429d410f3218f0b91c6",
  "slides": [
    {
      "id": "portfolio-v1-member",
      "title": "Where each track begins",
      "…": "every other key, as the chapter file holds it"
    }
  ],
  "basedOn": { "portfolio-v1-member": "<64 hex characters>" },
  "proposedBy": {
    "operatorSub": "<the operator's sub>",
    "tenantId": "<the tenant>"
  },
  "createdAt": "2026-09-21T12:00:00.000Z"
}

The digest in basedOn#

The digest is EI.7.07's definition. There is no second one. canonicalSlideSha256 in BA/presentation-library.ts and canonical_slide_sha256 in eve_change.py produce the same bytes. Both hash the slide object as its chapter file holds it:

  • object keys sorted at every depth, in UTF-16 code-unit order (which is how ECMAScript sorts; Python sorts by code point, and the two orders differ above U+FFFF);
  • arrays in their own order, with no insignificant whitespace, as UTF-8;
  • each number as JSON.parse reads it and ECMAScript prints it: 5.0 is 5, and an integer past 2⁵³ becomes its nearest double. A non-zero number outside [10⁻⁴, 10¹⁶) is refused rather than hashed, because the two languages print it differently. A lone surrogate is also refused, because UTF-8 cannot carry it.

Both sides pin the same vector (PYTHON_VECTOR in the library spec, BFF_VECTOR in test_eve_change.py). On 21 September 2026 the two agreed on all 1,721 library slides, with 0 differing.

A replacement slide must be hashable too. The BFF's loader hashes every slide it reads and refuses the whole library over one it cannot hash. The runner therefore reports such a slide under the rule canonical before the change can be applied.

What the runner says about a draft#

eve_change.py validate answers {ok, findings}. Each finding is {slideId, rule, message}, and slideId is null when the finding is about the draft as a whole. preview gives the same findings and renders nothing while there are any.

Rule Scope Meaning
draft draft Not a drafts/eve-<UUID>.json plain file in this center, absent, or not a JSON object.
publication draft An immutable Eve publication takes no drafts.
sourceRevision, title, slides, proposedBy, createdAt, basedOn draft The field is missing or malformed.
id slide No such library slide, or the same slide is replaced twice.
canonical slide The replacement cannot be hashed as described above.
basedOn slide No digest is recorded for this slide, or the recorded digest names a slide the draft does not replace.
stale slide The library slide has changed since the proposal. Propose again; EI.9.01's apply refuses the same condition as stale_proposal.
a builder field (title, layout, composition.nodes, sourceRevision, …) slide One of the builder's named rules, raised as SlideRuleError by the chapter-file rules (library_slide) or by a validator of a draft build.
build slide Any other builder refusal, in the builder's own words (a missing committed source, a malformed graph).
budget draft Once every slide passes: a chapter the draft touches, with its replacements substituted, breaks a chapter budget (A3.G2) further than its entry in authoring/chapter-budget-exceptions.json allows (a second long title in a chapter excepted for one is a finding). The message names the chapter and the rule.

A refusal counts against the draft only if the slide it replaces still renders, and a budget finding only if the chapter met its budgets without the draft. If that slide fails too, or the chapter broke a budget already, the library itself is broken. That is an internal error, with exit 1, and it is never reported as a finding.

Why not build-eve-oshun.py --draft#

That command renders a manuscript. It gives every slide the draft's own title as the chapter and reads each slide's sources at the library pin. A change replaces slides whose chapters may pin another revision. On 21 September 2026, 138 of the 1,721 slides were in such chapters, and 7 of them could not be rendered at the library pin at all. eve_change.py preview puts each replacement through library_slide, which attaches its chapter and its pin, and then through render_draft. The manuscript path ignores these three keys too, but it is the wrong renderer for a change.

Its life#

  1. Proposed (EI.8.04). The draft is written atomically, then validated and previewed. The card names its content hash.
  2. Previewed (EI.8.05). The admin route asks the BFF whether the change belongs to the calling operator and tenant, using proposedBy, and only then serves .qa-draft-eve-<changeId>/.
  3. Discarded (EI.8.04's door) or applied (EI.9.01). Before its first write, apply records a journal beside the draft, eve-<changeId>.apply.json. It re-hashes each replaced slide against basedOn and writes nothing when one differs.