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

@ -117,13 +117,13 @@ import * as fs from 'node:fs'
import { Db, type DbHost, type HistoricalQueryHandle } from './db/db.js'
import {
importGraph,
isBackupData,
type BackupData,
isPortableGraph,
type PortableGraph,
type ExportSelector,
type ExportOptions,
type ImportOptions,
type ImportResult
} from './db/backup.js'
} from './db/portableGraph.js'
import { GenerationStore } from './db/generationStore.js'
import { isDeterministicEmbedMode } from './embeddings/deterministicEmbedMode.js'
import { GenerationConflictError } from './db/errors.js'
@ -5074,22 +5074,22 @@ export class Brainy<T = any> implements BrainyInterface<T> {
}
/**
* @description Serialize part or all of the brain into a portable `BackupData`
* @description Serialize part or all of the brain into a portable `PortableGraph`
* document sugar for `brain.now().export(selector, options)` (the current
* generation). For a past generation use `(await brain.asOf(g)).export(...)`;
* for a speculative state use `brain.now().with(ops).export(...)`.
*
* Restore a `BackupData` with {@link Brainy.import} (it dispatches a backup to the
* Restore a `PortableGraph` with {@link Brainy.import} (it dispatches a backup to the
* graph round-trip; a file/buffer to ingestion). Distinct from `db.persist()`
* (native whole-brain snapshot with generation history).
*
* @param selector - WHAT to export (omit for the whole brain). See {@link ExportSelector}.
* @param options - HOW to export (vectors / VFS bytes / edge policy). See {@link ExportOptions}.
* @returns A versioned, portable `BackupData` document.
* @returns A versioned, portable `PortableGraph` document.
* @example
* const backup = await brain.export({ ids }, { includeVectors: true })
*/
async export(selector: ExportSelector = {}, options: ExportOptions = {}): Promise<BackupData> {
async export(selector: ExportSelector = {}, options: ExportOptions = {}): Promise<PortableGraph> {
return this.now().export(selector, options)
}
@ -6743,7 +6743,7 @@ export class Brainy<T = any> implements BrainyInterface<T> {
* - Reduced confusion (removed redundant options)
*/
async import(
source: Buffer | string | object | BackupData,
source: Buffer | string | object | PortableGraph,
options?: {
format?: 'excel' | 'pdf' | 'csv' | 'json' | 'markdown' | 'yaml' | 'docx' | 'image'
vfsPath?: string
@ -6770,9 +6770,9 @@ export class Brainy<T = any> implements BrainyInterface<T> {
}) => void
} & Partial<ImportOptions>
): Promise<ImportResult | any> {
// Portable graph round-trip: a BackupData document (produced by export()) is
// Portable graph round-trip: a PortableGraph document (produced by export()) is
// restored via ONE atomic transaction — distinct from foreign-file ingestion below.
if (isBackupData(source)) {
if (isPortableGraph(source)) {
return importGraph(this, this.storage, source, options as ImportOptions)
}