feat: includeHidden — export carries every visibility tier for migration-grade canon completeness

tests/unit/db/db-portable-graph.test.ts

@@ -453,3 +453,98 @@ describe('8.0 export enumeration:"canonical" — canon-complete against index bl
     ).rejects.toThrow(/enumeration:'canonical' requires a storage adapter/)
   })
 })
+
+describe('8.0 export includeHidden — every visibility tier for migration-grade canon completeness', () => {
+  // The fixed-id VFS root Brainy.init() always creates is the one 'system'-visibility
+  // entity a consumer can rely on existing (visibility:'system' is not settable via the
+  // public add() API — "intentionally not accepted", per AddParams.visibility's doc).
+  const VFS_ROOT_ID = '00000000-0000-0000-0000-000000000000'
+
+  let brain: Brainy
+
+  beforeEach(async () => {
+    brain = new Brainy(createTestConfig())
+    await brain.init()
+  })
+
+  afterEach(async () => {
+    await brain.close()
+  })
+
+  it('canonical + includeHidden carries an internal row AND the system row; round-trips through import', async () => {
+    const publicId = await brain.add({ data: 'Public', type: NounType.Thing, subtype: 'x' })
+    const internalId = await brain.add({
+      data: 'Internal',
+      type: NounType.Thing,
+      subtype: 'x',
+      visibility: 'internal'
+    })
+
+    const migrationExport = await brain.export({}, { enumeration: 'canonical', includeHidden: true })
+    const ids = migrationExport.entities.map((e) => e.id)
+    expect(ids).toContain(publicId)
+    expect(ids).toContain(internalId)
+    expect(ids).toContain(VFS_ROOT_ID)
+    expect(migrationExport.entities.find((e) => e.id === internalId)?.visibility).toBe('internal')
+    expect(migrationExport.entities.find((e) => e.id === VFS_ROOT_ID)?.visibility).toBe('system')
+
+    const target = new Brainy(createTestConfig())
+    await target.init()
+    try {
+      const result = await target.import(migrationExport)
+      expect(result.errors).toHaveLength(0)
+      expect((await target.get(internalId))?.visibility).toBe('internal')
+    } finally {
+      await target.close()
+    }
+  })
+
+  it('default export (includeHidden omitted) still excludes both hidden tiers — pins today\'s behavior', async () => {
+    const publicId = await brain.add({ data: 'Public', type: NounType.Thing, subtype: 'x' })
+    const internalId = await brain.add({
+      data: 'Internal',
+      type: NounType.Thing,
+      subtype: 'x',
+      visibility: 'internal'
+    })
+
+    for (const opts of [{ enumeration: 'index' as const }, { enumeration: 'canonical' as const }]) {
+      const backup = await brain.export({}, opts)
+      const ids = backup.entities.map((e) => e.id)
+      expect(ids).toContain(publicId)
+      expect(ids).not.toContain(internalId)
+      expect(ids).not.toContain(VFS_ROOT_ID)
+    }
+  })
+
+  it('index mode + includeHidden also reaches both tiers — find() takes includeInternal + includeSystem in one pass', async () => {
+    const publicId = await brain.add({ data: 'Public', type: NounType.Thing, subtype: 'x' })
+    const internalId = await brain.add({
+      data: 'Internal',
+      type: NounType.Thing,
+      subtype: 'x',
+      visibility: 'internal'
+    })
+
+    const indexExport = await brain.export({}, { enumeration: 'index', includeHidden: true })
+    const canonicalExport = await brain.export({}, { enumeration: 'canonical', includeHidden: true })
+
+    const indexIds = indexExport.entities.map((e) => e.id).sort()
+    const canonicalIds = canonicalExport.entities.map((e) => e.id).sort()
+    expect(indexIds).toEqual(canonicalIds)
+    expect(indexIds).toContain(publicId)
+    expect(indexIds).toContain(internalId)
+    expect(indexIds).toContain(VFS_ROOT_ID)
+  })
+
+  it('drift stays pure under includeHidden — no tier-policy noise when the index is healthy', async () => {
+    await brain.add({ data: 'Public', type: NounType.Thing, subtype: 'x' })
+    await brain.add({ data: 'Internal', type: NounType.Thing, subtype: 'x', visibility: 'internal' })
+
+    const audited = await brain.export(
+      {},
+      { enumeration: 'canonical', includeHidden: true, reportIndexDrift: true }
+    )
+    expect(audited.drift).toEqual({ canonicalOnly: [], indexOnly: [] })
+  })
+})