M9: a campaign you can actually get back

A campaign could already be exported and imported. What could not survive the
trip was everything that explains it: the state events behind the authoritative
document, the prompt each turn was actually given, the passages it was shown,
the summaries that carry long-story continuity, and which take belonged to which
turn. An imported campaign could be read and could no longer say why it was what
it was — and a manual correction, the one state change no narration explains,
was indistinguishable from something the story had established.

The bundle is now `ai-dnd-adventure-v3`, and the version is the design rather
than a side effect. Everything added here could have been another optional key,
the way persona, Save Points, narrative state and imported knowledge each were.
That mechanism stops working at exactly this addition: a v2 file with no prompt
provenance is ambiguous between "written before M9" and "written by M9 from a
campaign that has none", and those are different facts about a campaign. A
version number is how a recovery file states what it was capable of recording.
v1 and v2 still import, and every seam from pre-active-head onward is tested for
the rule that an older file is never reinterpreted under a newer assumption.

Two categories became three. "Chosen travels, derived is recomputed" was enough
until stored prompts had to be decided: they are derived, and they must travel
anyway. The test that separates evidence from cache is not "could this be
recomputed" but "would a recomputation answer the same question" — a rebuilt
search index answers the same question, a rebuilt prompt says what the turn
would be told *now*, which is the opposite of what the inspector is for.

Also here: a real SQLite backup, through the online backup API rather than a
file copy, taken while the application is running and verified before it is
kept; story cards settled as compatibility-only legacy data and taken out of the
narrator's prompt, because they were the untracked path around knowledge
authority that IMPORTED-KNOWLEDGE-DESIGN §73 already forbade; and no schema
change at all, proved against a database M8's own code wrote.

Three defects, found by running the milestone's own tests rather than by reading
them. Deleting a campaign leaked its FTS index rows, and SQLite then handed the
freed ids to the next source imported into any campaign, which failed with an
integrity error that Reindex could not repair — both ends are closed, and a
database already carrying the damage now repairs itself. An imported node with
no state snapshot was being stamped with the campaign's head state, so an Undo
to turn 2 showed what the story knew at turn 20. And the snapshot relink did not
persist at all, because it mutated a dict in place on a column SQLAlchemy tracks
by assignment: it looked correct in memory and wrote the wrong ids to disk.

Carrying per-turn prompts looked like it would halve the length of campaign that
can be restored. Measured — and after compressing them inside the file —
everything M9 added costs 12% of it: the import ceiling moves from about 318
turns to about 279, against a 100-turn certification target. The dominant cost
is not M9's at all. The per-position narrative state document is 74% of a
bundle, and v2 already carried it.

Backend 1,102 passed / 14 skipped / 0 failed. Frontend 145 passed. Lint,
production build and Docker build clean. Verified across two server processes
with two data directories, and in a real browser against a real narrator.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qyn3oRd4D6pi72nKBG725B

frontend/src/api.js

@@ -153,6 +153,14 @@ export const api = {
   retry: (advId, handlers, signal) => streamSSE(`/adventures/${advId}/retry`, {}, handlers, signal),
   exportAdventure: (id) => request(`/adventures/${id}/export`),
   importAdventure: (bundle) => request('/adventures/import', { method: 'POST', body: JSON.stringify(bundle) }),
+
+  // M9. A verified copy of the whole database, which is a different tool from
+  // exporting one campaign: the export moves a campaign between installations,
+  // and this is a safety copy of everything on this machine. Neither takes a
+  // path — the server derives the destination from the database it already has
+  // open, so there is nothing here for a caller to point somewhere else.
+  listBackups: () => request('/backups'),
+  createBackup: () => request('/backups', { method: 'POST' }),
   undo: (advId) => request(`/adventures/${advId}/undo`, { method: 'POST' }),
   // Undo moves the story back without deleting it, so there is somewhere to
   // move forward to again (M3). Both answer with the newest window.

frontend/src/components.jsx

@@ -15,17 +15,53 @@ export function pickJSONFile() {
     const input = document.createElement('input')
     input.type = 'file'
     input.accept = '.json,application/json'
+    // M9: in the document, and driveable, rather than detached.
+    //
+    // A detached input is what this was, and `.click()` on one opens the
+    // browser's file dialog in Firefox and Chrome today — but it is not
+    // something the HTML spec requires, and it made the one control that
+    // recovers a campaign impossible to drive from a browser test: there is no
+    // element for WebDriver to hand a path to, so the import workflow could
+    // only ever be checked by calling the API underneath it.
+    //
+    // Taken out of layout rather than marked `hidden`, and the difference is
+    // load-bearing. A `hidden` input is non-interactable, and WebDriver will
+    // set `files` on one without dispatching `change` — so the file lands and
+    // nothing happens, which is a worse failure than the detached input was
+    // because it looks like it worked. This is the ordinary visually-hidden
+    // file-input pattern: off-screen, zero-sized, out of the accessibility
+    // tree and out of the tab order, so no reader meets a stray "Choose file"
+    // control while the browser's own dialog is what they are looking at.
+    input.setAttribute('aria-hidden', 'true')
+    input.tabIndex = -1
+    input.style.cssText =
+      'position:fixed;left:-9999px;width:1px;height:1px;opacity:0;pointer-events:none'
+    input.dataset.testid = 'import-file'
+    const done = (settle) => (value) => { input.remove(); settle(value) }
+    const ok = done(resolve)
+    const bad = done(reject)
+    // M9: a cancelled dialog settles the promise.
+    //
+    // It did not before. `onchange` does not fire when the reader closes the
+    // picker without choosing anything, so the promise stayed pending forever
+    // — and the Campaigns screen awaits it, so its `finally` never ran and the
+    // Import button sat disabled reading "Importing…" until the page was
+    // reloaded. The rejection carries an empty message, because that screen
+    // already treats a message-less error as "they changed their mind" and
+    // says nothing: a cancelled dialog is not a failure to report.
+    input.oncancel = () => bad(Object.assign(new Error(), { message: '' }))
     input.onchange = () => {
       const file = input.files[0]
-      if (!file) return reject(new Error('No file selected'))
+      if (!file) return bad(new Error('No file selected'))
       const reader = new FileReader()
       reader.onload = () => {
-        try { resolve(JSON.parse(reader.result)) }
-        catch { reject(new Error('Not valid JSON')) }
+        try { ok(JSON.parse(reader.result)) }
+        catch { bad(new Error('Not valid JSON')) }
       }
-      reader.onerror = () => reject(new Error('Could not read file'))
+      reader.onerror = () => bad(new Error('Could not read file'))
       reader.readAsText(file)
     }
+    document.body.appendChild(input)
     input.click()
   })
 }

frontend/src/filePicker.test.jsx

@@ -0,0 +1,110 @@
+/* M9: the file picker that recovers a campaign.
+ *
+ * `pickJSONFile` is four lines of DOM and was the only control in the product
+ * with no test at all, for a structural reason: it built a detached
+ * `<input type="file">` and clicked it, so there was no element for a test — or
+ * for WebDriver — to hand a file to. The import workflow could therefore only
+ * ever be checked by calling the API underneath it, which is not the workflow.
+ *
+ * Appending the input made it testable, and writing the test found a real bug
+ * that had been there since the picker was written: closing the dialog without
+ * choosing anything never settled the promise, so the Campaigns screen's
+ * `finally` never ran and its Import button stayed disabled reading
+ * "Importing…" until the page was reloaded. The screen's own comment says a
+ * cancelled picker is not worth a message — it had just never received one.
+ */
+
+import { fireEvent } from '@testing-library/react'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { pickJSONFile } from './components'
+
+function theInput() {
+  return document.querySelector('input[type="file"]')
+}
+
+/** A `File` the way the browser hands one to a change event. */
+function jsonFile(name, contents) {
+  return new File([JSON.stringify(contents)], name, { type: 'application/json' })
+}
+
+/** Puts `files` on the input, since `files` is read-only in jsdom. */
+function choose(input, files) {
+  Object.defineProperty(input, 'files', { value: files, configurable: true })
+  fireEvent.change(input)
+}
+
+beforeEach(() => { document.body.innerHTML = '' })
+
+describe('pickJSONFile', () => {
+  it('puts a findable input in the document rather than a detached one', () => {
+    pickJSONFile().catch(() => {})
+    const input = theInput()
+    expect(input).toBeInTheDocument()
+    expect(input.dataset.testid).toBe('import-file')
+    expect(input.accept).toContain('json')
+    // Out of sight, out of the tab order and out of the accessibility tree,
+    // because the reader is looking at the browser's own dialog — but **not**
+    // `hidden`, which would make it non-interactable and stop the browser
+    // dispatching `change` when a file is chosen programmatically.
+    expect(input.hidden).toBe(false)
+    expect(input.getAttribute('aria-hidden')).toBe('true')
+    expect(input.tabIndex).toBe(-1)
+    expect(input.style.position).toBe('fixed')
+  })
+
+  it('resolves with the parsed bundle', async () => {
+    const promise = pickJSONFile()
+    choose(theInput(), [jsonFile('c.json', { format: 'ai-dnd-adventure-v3' })])
+    await expect(promise).resolves.toEqual({ format: 'ai-dnd-adventure-v3' })
+  })
+
+  it('rejects a file that is not JSON, with a message worth showing', async () => {
+    const promise = pickJSONFile()
+    const input = theInput()
+    Object.defineProperty(input, 'files', {
+      value: [new File(['not json at all'], 'c.json')], configurable: true,
+    })
+    fireEvent.change(input)
+    await expect(promise).rejects.toThrow(/not valid json/i)
+  })
+
+  it('settles even when the file cannot be read, rather than hanging', async () => {
+    // A real case, not a defensive one. A browser can hand the page a `File`
+    // whose contents it will not then let the page read — a sandboxed Firefox
+    // does exactly that for a path outside its confinement, and reports
+    // `NotFoundError` from the FileReader with the name and size intact.
+    // Whatever happens, the promise must settle: leaving it pending is what
+    // left the Import button disabled reading "Importing…".
+    const promise = pickJSONFile()
+    const input = theInput()
+    Object.defineProperty(input, 'files', {
+      value: [jsonFile('c.json', { ok: true })], configurable: true,
+    })
+    fireEvent.change(input)
+    await expect(Promise.race([
+      promise.then(() => 'settled', () => 'settled'),
+      new Promise((r) => { setTimeout(() => r('hung'), 300) }),
+    ])).resolves.toBe('settled')
+  })
+
+  it('settles when the dialog is cancelled, instead of hanging forever', async () => {
+    const promise = pickJSONFile()
+    fireEvent(theInput(), new Event('cancel'))
+    // Rejected, so the caller's `finally` runs — and with no message, so the
+    // caller shows nothing. Both halves matter: a hang leaves the button
+    // disabled, and a message would report a decision as a failure.
+    await expect(promise).rejects.toSatisfy((err) => err.message === '')
+  })
+
+  it('takes the input back out of the document however it settles', async () => {
+    const resolved = pickJSONFile()
+    choose(theInput(), [jsonFile('c.json', { ok: true })])
+    await resolved
+    expect(theInput()).toBeNull()
+
+    const cancelled = pickJSONFile()
+    fireEvent(theInput(), new Event('cancel'))
+    await cancelled.catch(() => {})
+    expect(theInput()).toBeNull()
+  })
+})

frontend/src/pages/Settings.jsx

@@ -85,6 +85,105 @@ function DebugLog() {
   )
 }
 
+
+/* M9. A verified copy of the whole database, on this machine.
+ *
+ * Deliberately small, and deliberately not a second export. The campaign export
+ * on the Campaigns screen is the tool for moving one campaign to another
+ * installation; this is the tool for keeping a copy of everything before doing
+ * something risky. Conflating them would leave a reader guessing which one
+ * answers "how do I not lose my campaigns".
+ *
+ * There is no restore button and no download link, and both absences are
+ * decisions rather than gaps:
+ *
+ *   * **Restore** means replacing the file the running application has open,
+ *     which is how somebody loses both copies at once. `DEVELOPMENT.md` carries
+ *     the procedure — stop the app, move the file, start it — and it is a
+ *     procedure precisely because each step needs the app to be stopped.
+ *   * **Download** would put a copy of every campaign on the machine into the
+ *     browser's download directory and its cache. For an application whose
+ *     premise is that the story does not leave the machine, a path the reader
+ *     can copy is the better default.
+ */
+function DatabaseBackup() {
+  const toast = useToast()
+  const [state, setState] = useState(null)
+  const [busy, setBusy] = useState(false)
+
+  const load = () => {
+    api.listBackups()
+      .then(setState)
+      .catch((err) => toast(err.message, 'error'))
+  }
+
+  const take = async () => {
+    setBusy(true)
+    try {
+      const result = await api.createBackup()
+      toast(`Backup written: ${result.filename} (${formatBytes(result.bytes)}).`)
+      load()
+    } catch (err) {
+      toast(err.message, 'error')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <details
+      className="advanced-block"
+      data-testid="database-backup"
+      onToggle={(e) => { if (e.currentTarget.open && state === null) load() }}
+    >
+      <summary>Back up everything on this machine</summary>
+      <p className="field-hint">
+        Writes a verified copy of the whole database — every campaign, every
+        imported file, every setting — beside the database itself. The copy is
+        checked before it is kept, and an existing backup is never overwritten.
+        To export a single campaign so it can be opened somewhere else, use
+        Export on the campaign instead.
+      </p>
+      <div className="panel-actions">
+        <button type="button" className="primary" onClick={take} disabled={busy}>
+          {busy ? 'Backing up…' : 'Back up now'}
+        </button>
+      </div>
+      {state && (
+        <>
+          <p className="field-hint">
+            Backups are written to <code>{state.directory}</code>. To restore
+            one, stop the application, put the file in place of the database, and
+            start it again.
+          </p>
+          {state.backups.length === 0 ? (
+            <p className="dim">No backups yet.</p>
+          ) : (
+            <ul className="backup-list">
+              {state.backups.map((b) => (
+                <li key={b.filename}>
+                  <code>{b.filename}</code>
+                  <span className="dim">
+                    {' '}{formatBytes(b.bytes)} · {new Date(b.taken_at).toLocaleString()}
+                  </span>
+                </li>
+              ))}
+            </ul>
+          )}
+        </>
+      )}
+    </details>
+  )
+}
+
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) return ''
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} kB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+
 export default function Settings() {
   const [settings, setSettings] = useState(null)
   const [testResult, setTestResult] = useState(null)
@@ -347,6 +446,8 @@ export default function Settings() {
           </div>
         </details>
 
+        <DatabaseBackup />
+
         <DebugLog />
       </section>
     </div>

frontend/src/pages/backup.test.jsx

@@ -0,0 +1,116 @@
+/* M9: the database backup control, and what it must not become.
+ *
+ * The control itself is three lines of state, so the interesting assertions are
+ * about the boundaries around it rather than about the button:
+ *
+ *   * it is **not** an export. The campaign export moves one campaign to
+ *     another installation; this copies everything on this machine. A reader
+ *     who cannot tell them apart has no way to answer "how do I not lose my
+ *     campaigns", so the panel says which is which.
+ *   * it offers **no restore and no download**, and both are decisions. Restore
+ *     means replacing the file the running application has open; download means
+ *     putting every campaign on the machine into the browser's cache.
+ *   * a failure **says so**. A backup that silently did not happen is worse
+ *     than no backup, because the reader believes they have one.
+ */
+
+import { screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { api } from '../api'
+import Settings from './Settings'
+import { mockModelStatus, renderWith } from '../test/helpers'
+
+const LISTING = {
+  directory: '/home/reader/.adventure/backups',
+  backups: [
+    { filename: 'adventure-storyteller-20260907-043000.db', bytes: 2_400_000,
+      taken_at: '2026-09-07T04:30:00' },
+    { filename: 'adventure-storyteller-20260901-101500.db', bytes: 2_100_000,
+      taken_at: '2026-09-01T10:15:00' },
+  ],
+}
+
+beforeEach(() => { vi.restoreAllMocks() })
+
+async function openTheBackupPanel() {
+  mockModelStatus(api)
+  vi.spyOn(api, 'listBackups').mockResolvedValue(LISTING)
+  await renderWith(<Settings />)
+  const panel = screen.getByTestId('database-backup')
+  await userEvent.click(screen.getByText(/Back up everything on this machine/i))
+  return panel
+}
+
+describe('the backup control', () => {
+  it('lists the backups already on disk, and where they are', async () => {
+    await openTheBackupPanel()
+    await waitFor(() => {
+      expect(screen.getByText('adventure-storyteller-20260907-043000.db')).toBeInTheDocument()
+    })
+    expect(screen.getByText('adventure-storyteller-20260901-101500.db')).toBeInTheDocument()
+    expect(screen.getByText('/home/reader/.adventure/backups')).toBeInTheDocument()
+  })
+
+  it('takes a backup and reports what was written', async () => {
+    const panel = await openTheBackupPanel()
+    const create = vi.spyOn(api, 'createBackup').mockResolvedValue({
+      directory: LISTING.directory,
+      filename: 'adventure-storyteller-20260907-050000.db',
+      bytes: 2_500_000, pages: 610, seconds: 0.02, integrity: 'ok',
+    })
+    await userEvent.click(screen.getByRole('button', { name: /Back up now/i }))
+    await waitFor(() => expect(create).toHaveBeenCalled())
+    expect(await screen.findByText(/Backup written/)).toBeInTheDocument()
+    expect(screen.getByText(/adventure-storyteller-20260907-050000\.db/)).toBeInTheDocument()
+    expect(panel).toBeInTheDocument()
+  })
+
+  it('reloads the list afterwards, so the new file is visible', async () => {
+    await openTheBackupPanel()
+    vi.spyOn(api, 'createBackup').mockResolvedValue({
+      directory: LISTING.directory, filename: 'new.db', bytes: 1, integrity: 'ok',
+    })
+    await userEvent.click(screen.getByRole('button', { name: /Back up now/i }))
+    await waitFor(() => expect(api.listBackups).toHaveBeenCalledTimes(2))
+  })
+
+  it('reports a failure rather than looking as though it worked', async () => {
+    await openTheBackupPanel()
+    vi.spyOn(api, 'createBackup').mockRejectedValue(
+      new Error('The backup was written but did not verify: page 4 missing.'),
+    )
+    await userEvent.click(screen.getByRole('button', { name: /Back up now/i }))
+    expect(await screen.findByText(/did not verify/)).toBeInTheDocument()
+    expect(screen.queryByText(/Backup written/)).not.toBeInTheDocument()
+  })
+
+  it('says which tool this is, and which one moves one campaign', async () => {
+    await openTheBackupPanel()
+    expect(screen.getByText(/every campaign, every/i)).toBeInTheDocument()
+    expect(
+      screen.getByText(/To export a single campaign so it can be opened somewhere else/i),
+    ).toBeInTheDocument()
+  })
+
+  it('offers no restore button and no download link', async () => {
+    const panel = await openTheBackupPanel()
+    await waitFor(() => {
+      expect(screen.getByText(LISTING.directory)).toBeInTheDocument()
+    })
+    const labels = [...panel.querySelectorAll('button')].map((b) => b.textContent)
+    expect(labels.some((label) => /restore/i.test(label))).toBe(false)
+    expect(labels.some((label) => /download/i.test(label))).toBe(false)
+    expect(panel.querySelectorAll('a[download]')).toHaveLength(0)
+    expect(panel.querySelectorAll('a[href]')).toHaveLength(0)
+    // And the procedure is stated instead, so the absence is an answer.
+    expect(screen.getByText(/stop the application/i)).toBeInTheDocument()
+  })
+
+  it('does not fetch anything until the panel is opened', async () => {
+    mockModelStatus(api)
+    const list = vi.spyOn(api, 'listBackups').mockResolvedValue(LISTING)
+    await renderWith(<Settings />)
+    expect(list).not.toHaveBeenCalled()
+  })
+})

frontend/src/styles/library.css

@@ -204,6 +204,21 @@
 }
 .advanced-block > summary:hover { color: var(--text); }
 .advanced-block h4 { margin: 10px 0 4px; font-size: 0.74rem; color: var(--text-dim); }
+/* M9: the list of database backups already on disk. A filename, a size and a
+   time — enough to recognise one, and nothing that needs a table. */
+.backup-list {
+  margin: 8px 0 0;
+  padding: 0;
+  list-style: none;
+  font-size: 0.78rem;
+}
+.backup-list li {
+  padding: 3px 0;
+  border-top: 1px solid var(--border);
+  /* A long filename wraps rather than pushing the panel sideways. */
+  overflow-wrap: anywhere;
+}
+.backup-list li:first-child { border-top: none; }
 .advanced-block pre {
   max-height: 16em;
   overflow: auto;