# Eve change drafts

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.
