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

18
tests/unit/api/data-backup.test.ts → tests/unit/api/data-portable-graph.test.ts
View file

@ -1,7 +1,7 @@
/**
* Unit tests for the portable graph backup/restore API (brain.data()).
*
* Exercises BackupData v1 export()/import(): real round-trips against in-memory
* Exercises PortableGraph v1 export()/import(): real round-trips against in-memory
* storage (no mocks of the API under test) — selectors, edge policy, vectors,
* conflict handling, id remapping, subtype fidelity, and cross-version guards.
*/
@ -11,11 +11,11 @@ import { randomUUID } from 'node:crypto'
import { Brainy } from '../../../src/brainy'
import { createTestConfig } from '../../helpers/test-factory'
import { NounType, VerbType } from '../../../src/types/graphTypes'
import type { BackupData } from '../../../src/api/DataAPI'
import type { PortableGraph } from '../../../src/api/DataAPI'
const VFS_ROOT_ID = '00000000-0000-0000-0000-000000000000'
describe('DataAPI — portable graph backup/restore (BackupData v1)', () => {
describe('DataAPI — portable graph backup/restore (PortableGraph v1)', () => {
let brain: Brainy
beforeEach(async () => {
@ -28,14 +28,14 @@ describe('DataAPI — portable graph backup/restore (BackupData v1)', () => {
})
describe('format + whole-brain round-trip', () => {
it('exports a self-describing, versioned BackupData document', async () => {
it('exports a self-describing, versioned PortableGraph document', async () => {
const a = await brain.add({ data: 'Alice', type: NounType.Person, subtype: 'employee' })
const b = await brain.add({ data: 'Acme', type: NounType.Organization })
await brain.relate({ from: a, to: b, type: VerbType.WorksWith, subtype: 'full-time' })
const backup = await brain.data().then((d) => d.export())
expect(backup.format).toBe('brainy-backup')
expect(backup.format).toBe('brainy-portable-graph')
expect(backup.formatVersion).toBe(1)
expect(typeof backup.brainyVersion).toBe('string')
expect(backup.brainyVersion.length).toBeGreaterThan(0)
@ -288,15 +288,15 @@ describe('DataAPI — portable graph backup/restore (BackupData v1)', () => {
})
describe('import validation', () => {
it('rejects a non-BackupData payload', async () => {
it('rejects a non-PortableGraph payload', async () => {
const d = await brain.data()
await expect(d.import({ entities: [] } as any)).rejects.toThrow(/BackupData/)
await expect(d.import({ entities: [] } as any)).rejects.toThrow(/PortableGraph/)
})
it('rejects a newer formatVersion', async () => {
const d = await brain.data()
const future: BackupData = {
format: 'brainy-backup',
const future: PortableGraph = {
format: 'brainy-portable-graph',
formatVersion: 999,
brainyVersion: 'x',
createdAt: new Date().toISOString(),