docs(8.0): export/import guide + api/README portable backup section

- New docs/guides/export-and-import.md (public) for the 8.0 surface:
  brain.export()/import(), Db composition (asOf/with time-travel + what-if export),
  selectors, options, BackupData v1 format, cross-version (7.x→8.0), VFS, and the
  generations/persist distinction. Documents only the implemented surface.
- api/README "Export & Import (portable) + Snapshots (native)": adds the portable
  brain.export()/import() round-trip alongside the native persist()/asOf() snapshot.
This commit is contained in:
David Snelling 2026-06-17 11:24:57 -07:00
parent 010ccf816d
commit c2b73d4564
2 changed files with 207 additions and 1 deletions

View file

@ -1413,7 +1413,32 @@ await brain.import('https://api.example.com/data.json')
---
### Export & Snapshots
### Export & Import (portable) + Snapshots (native)
**Portable graph backup** — `brain.export()` / `brain.import()` (`BackupData` v1, versioned
JSON, partial-or-whole, cross-version). `export()` lives on the immutable `Db`, so it composes
with `now()`/`asOf()`/`with()`:
```typescript
// Export part or all of the brain to a portable, versioned document
const backup = await brain.export({ ids }, { includeVectors: true })
// Restore it — import() routes a BackupData to the graph round-trip (merge by id)
await otherBrain.import(backup, { onConflict: 'merge' })
// Time-travel export (serialize a past generation) / what-if export (a speculative state)
const past = await brain.asOf(gen)
const asWas = await past.export({ collection: id })
await past.release()
await brain.now().with(ops).export({ ids })
```
Selectors: `{ ids }`, `{ collection }` (alias `memberOf`), `{ connected: { from, depth } }`,
`{ vfsPath }`, predicate (`{ type, subtype, where, service }`), or whole brain (omit). See the
**[Export & Import guide](../guides/export-and-import.md)**. Distinct from `brain.import(file)`
(CSV/PDF/Excel/JSON ingestion — `import()` dispatches on whether you pass a `BackupData` or a file).
**Native whole-brain snapshot** (generation-preserving, not portable JSON):
```typescript
// Instant hard-link snapshot via the Db API