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

The export()/import() document type was named BackupData, but it is not a backup:
it is the portable, versioned, partial-or-whole interchange representation of a
graph (entities + relations + optional vectors/blobs) — the unit Brainy exports
for transport between instances, versions, and products, and the payload other
artifacts embed. The actual backup is persist()/load() (the native whole-brain,
generation-preserving snapshot), so "Backup*" actively collided with that concept.

Rename every developer-visible symbol, file, doc, JSDoc and comment:
- BackupData→PortableGraph, BackupEntity→PortableGraphEntity,
  BackupRelation→PortableGraphRelation, BackupReader/Writer→PortableGraphReader/Writer,
  BackupValidation→PortableGraphValidation, isBackupData→isPortableGraph,
  validateBackup→validatePortableGraph, BACKUP_FORMAT[_VERSION]→PORTABLE_GRAPH_FORMAT[_VERSION].
- src/db/backup.ts → src/db/portableGraph.ts; test → db-portable-graph.test.ts.
- Guide, api/README, RELEASES updated.

The on-the-wire `format` tag is renamed 'brainy-backup' → 'brainy-portable-graph':
the 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. No deprecated aliases (nothing to alias). 7.x shipped the
same rename as 7.32.2.

1471 unit green; build clean; db-portable-graph.test.ts 17/17.
This commit is contained in:
David Snelling 2026-06-19 12:09:19 -07:00
parent 3a3aa43b3a
commit 373a48122d
8 changed files with 156 additions and 145 deletions

View file

@ -142,19 +142,19 @@ export { EntityNotFoundError, RelationNotFoundError } from './errors/notFound.js
// db.with() / db.persist() / Brainy.load(). See src/db/ for the record layer.
export { Db } from './db/db.js'
// Portable graph backup/restore — db.export() / brain.export() / brain.import()
// (BackupData v1; identical wire format to the 7.x line).
export { isBackupData, validateBackup } from './db/backup.js'
// Portable graph export/import — db.export() / brain.export() / brain.import()
// (PortableGraph v1; identical wire format to the 7.x line).
export { isPortableGraph, validatePortableGraph } from './db/portableGraph.js'
export type {
BackupData,
BackupEntity,
BackupRelation,
PortableGraph,
PortableGraphEntity,
PortableGraphRelation,
ExportSelector,
ExportOptions,
ImportOptions,
ImportResult,
BackupValidation
} from './db/backup.js'
PortableGraphValidation
} from './db/portableGraph.js'
export {
GenerationConflictError,
SpeculativeOverlayError,