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:
parent
3a3aa43b3a
commit
373a48122d
8 changed files with 156 additions and 145 deletions
21
RELEASES.md
21
RELEASES.md
|
|
@ -80,7 +80,7 @@ historical records) are documented in:
|
|||
- [docs/ADR-001-generational-mvcc.md](docs/ADR-001-generational-mvcc.md) — the
|
||||
design record: persisted layout, commit protocol, crash recovery, proof table
|
||||
|
||||
### Portable export & import (BackupData v1)
|
||||
### Portable export & import (PortableGraph v1)
|
||||
|
||||
A portable, versioned graph format that serializes part or all of a brain to a
|
||||
single JSON document and restores it — the cross-environment, cross-version
|
||||
|
|
@ -88,29 +88,34 @@ single JSON document and restores it — the cross-environment, cross-version
|
|||
|
||||
```ts
|
||||
// Export is a method on the immutable Db, so it composes with now()/asOf()/with()
|
||||
const backup = await brain.export({ collection: id }, { includeVectors: true })
|
||||
await otherBrain.import(backup, { onConflict: 'merge' }) // dedup-by-id
|
||||
const graph = await brain.export({ collection: id }, { includeVectors: true })
|
||||
await otherBrain.import(graph, { onConflict: 'merge' }) // dedup-by-id
|
||||
|
||||
;(await brain.asOf(gen)).export(sel) // time-travel export
|
||||
brain.now().with(ops).export(sel) // what-if export
|
||||
```
|
||||
|
||||
- **`brain.export(selector?, options?)` / `db.export(...)`** → a versioned
|
||||
`BackupData` document. Selectors reuse `find()`'s grammar: `{ ids }`,
|
||||
`PortableGraph` document. Selectors reuse `find()`'s grammar: `{ ids }`,
|
||||
`{ collection }` (alias `memberOf`, transitive `Contains`),
|
||||
`{ connected: { from, depth } }`, `{ vfsPath }`, predicate
|
||||
(`{ type, subtype, where, service }`), or the whole brain (omit) — and they
|
||||
compose. Options: `includeVectors`, `includeContent` (VFS file bytes),
|
||||
`includeSystem`, `edges: 'induced' | 'incident' | 'none'`.
|
||||
- **`brain.import(backup, options?)`** is polymorphic: a `BackupData` document is
|
||||
- **`brain.import(graph, options?)`** is polymorphic: a `PortableGraph` document is
|
||||
restored as **one atomic transaction** (`onConflict: 'merge' | 'replace' | 'skip'`,
|
||||
`reembed: 'auto' | 'never'`, `remapIds` for cloning); a file/buffer routes to the
|
||||
existing CSV/PDF/Excel/JSON ingestion. No migration for ingestion callers.
|
||||
- **`validateBackup(data)`** — dry-run structural/version/endpoint check before import.
|
||||
- **Format** (`format:'brainy-backup'`, `formatVersion: 1`) is identical on 7.x
|
||||
(7.32.0) and 8.0; standard fields (`subtype`/`visibility`/`data`/…) are top-level,
|
||||
- **`validatePortableGraph(data)`** — dry-run structural/version/endpoint check before import.
|
||||
- **Format** (`format:'brainy-portable-graph'`, `formatVersion: 1`) is identical on
|
||||
7.x and 8.0; standard fields (`subtype`/`visibility`/`data`/…) are top-level,
|
||||
`metadata` is custom-only. Current-state (no generation history — that lives in
|
||||
`persist()`). Types exported from the package root.
|
||||
- **Naming:** the type is `PortableGraph` (with `PortableGraphEntity` /
|
||||
`PortableGraphRelation`) — it is the portable interchange form of a graph, not a
|
||||
backup (that role is `persist()`/`load()`). Renamed from the short-lived
|
||||
`BackupData`/`'brainy-backup'` (introduced in 7.32.0, never adopted) with no
|
||||
compatibility shim.
|
||||
- Guide: [docs/guides/export-and-import.md](docs/guides/export-and-import.md).
|
||||
|
||||
### Aggregation: distinctCount over any value type
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue