soulcraft/brainy
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases 335 Packages Wiki Activity Actions

refactor: rename BackupData → PortableGraph (the type is interchange, not a backup)

Browse source 
Parity with the 8.0 rename, backported to the 7.x line. The brain.data()
export()/import() document type was BackupData, but it is the portable, versioned
interchange representation of a graph (entities + relations + optional vectors),
NOT a backup — exported for transport between instances, versions, and products.
The actual backup is the native snapshot, so "Backup*" mis-signalled.

Rename every developer-visible symbol, JSDoc, comment and doc:
- BackupData→PortableGraph, BackupEntity→PortableGraphEntity,
  BackupRelation→PortableGraphRelation, BACKUP_FORMAT[_VERSION]→
  PORTABLE_GRAPH_FORMAT[_VERSION], internal toBackup* helpers→toPortableGraph*.
- src/api/DataAPI.ts, src/index.ts, src/cli/commands/core.ts, docs, and the test
  (renamed data-backup.test.ts → data-portable-graph.test.ts).

The on-the-wire `format` tag is also renamed 'brainy-backup' → 'brainy-portable-graph':
the export/import format was introduced in 7.32.0 and has not been adopted by any
consumer, so there are no stored documents to stay compatible with — a clean rename
beats carrying a legacy tag forward. No deprecated aliases (nothing to alias).

1505 unit green; build clean; data-portable-graph.test.ts 20/20.
This commit is contained in:
David Snelling 2026-06-19 12:15:07 -07:00
parent 5e7379dc41
commit 89036deb20
9 changed files with 98 additions and 95 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/api/README.md
View file

@ -1765,18 +1765,18 @@ await brain.import('https://api.example.com/data.json')
---
### Export & Import (portable backup)
### Export & Import (portable graph)
`brain.data()` exposes a portable graph backup/restore API. `export(selector?, options?)`
serializes part or all of the graph to a versioned, portable `BackupData` document;
`import(backup, options?)` restores it (dedup-by-id merge by default, re-embedding when
`brain.data()` exposes a portable graph graph/restore API. `export(selector?, options?)`
serializes part or all of the graph to a versioned, portable `PortableGraph` document;
`import(graph, options?)` restores it (dedup-by-id merge by default, re-embedding when
vectors are absent).
```typescript
const data = await brain.data()
// Whole brain → a portable BackupData document
const backup = await data.export()
// Whole brain → a portable PortableGraph document
const graph = await data.export()
// Just one workbench's members, with vectors, then restore elsewhere (merge by id)
const subset = await data.export({ ids }, { includeVectors: true })