feat(8.0): portable graph export()/import() (BackupData v1) — Db.export + polymorphic import

Re-adds the portable graph round-trip on 8.0 (deleted with DataAPI), now on the
immutable Db so it composes with the generational model.

- src/db/backup.ts: BackupData v1 engine (identical wire format to the 7.32.0 line).
  exportGraph() reads through a Db at its pinned generation; importGraph() applies the
  whole backup as ONE atomic transact() (a single generation).
- Db.export(selector?, options?) — read at this view's generation, so
  brain.asOf(g).export() is a time-travel export and brain.now().with(ops).export() a
  what-if export.
- brain.export(selector?, options?) — sugar for now().export().
- brain.import() is polymorphic: a BackupData document -> graph round-trip; a
  file/buffer -> existing foreign-file ingestion (dispatched on the 'brainy-backup'
  tag; zero migration for ingestion callers).
- Selectors (ids/collection/connected/vfsPath/predicate/whole) + edge policy
  (induced/incident/none) + includeVectors/includeContent/includeSystem; system
  entities excluded by visibility. onConflict merge/replace/skip, reembed auto/never,
  remapIds. DbHost gains storage (VFS blob bytes).
- Types exported from the package root: BackupData/BackupEntity/BackupRelation/
  ExportSelector/ExportOptions/ImportOptions/ImportResult + isBackupData.

Tests: tests/unit/db/db-backup.test.ts (10, green) — round-trip, selectors, edges,
vectors+re-embed, merge, asOf/with composition, validation. Full unit suite green.

Follow-ups: docs (8.0 guide + RELEASES + api/README), completeness adds
(since(prior).export() delta, exportStream/importStream, validate()), includeContent
filesystem test, ids-at-asOf get() refinement, @soulcraft/formats Zod schema mirror.
This commit is contained in:
David Snelling 2026-06-16 16:38:18 -07:00
parent f4dea80176
commit 010ccf816d
5 changed files with 948 additions and 4 deletions

View file

@ -141,6 +141,19 @@ export { EntityNotFoundError, RelationNotFoundError } from './errors/notFound.js
// Immutable database values: brain.now() / brain.transact() / brain.asOf() /
// 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 } from './db/backup.js'
export type {
BackupData,
BackupEntity,
BackupRelation,
ExportSelector,
ExportOptions,
ImportOptions,
ImportResult
} from './db/backup.js'
export {
GenerationConflictError,
SpeculativeOverlayError,