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.
{
"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.parsereads it and ECMAScript prints it:5.0is5, 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#
- Proposed (EI.8.04). The draft is written atomically, then validated and previewed. The card names its content hash.
- 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>/. - Discarded (EI.8.04's door) or applied (EI.9.01). Before its first
write,
applyrecords a journal beside the draft,eve-<changeId>.apply.json. It re-hashes each replaced slide againstbasedOnand writes nothing when one differs.