@dxos/plugin-space 0.8.4-main.fffef41 → 0.9.0

package/src/capabilities/app-graph-builder/extensions/database.ts

@@ -0,0 +1,432 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+
+import { Capability, type CapabilityManager } from '@dxos/app-framework';
+import { AppNode, AppNodeMatcher, LayoutOperation, Segments, getTypeSlug } from '@dxos/app-toolkit';
+import { type Space, SpaceState, isSpace } from '@dxos/client/echo';
+import { Operation } from '@dxos/compute';
+import { Annotation, Collection, Entity, Filter, Obj, Query, Scope, Type } from '@dxos/echo';
+import { HiddenAnnotation } from '@dxos/echo/Annotation';
+import { type URI } from '@dxos/keys';
+import { ClientCapabilities } from '@dxos/plugin-client';
+import { CreateAtom, GraphBuilder, Node } from '@dxos/plugin-graph';
+import { ViewAnnotation } from '@dxos/schema';
+import { createFilename, isNonNullable } from '@dxos/util';
+
+import { meta } from '#meta';
+import { SpaceOperation } from '#operations';
+import { SpaceCapabilities } from '#types';
+
+import { makeCreateObjectEntryForDatabaseType } from '../../../util';
+import {
+  ADD_VIEW_TO_SCHEMA_LABEL,
+  BLOCK_REORDER_ABOVE,
+  SNAPSHOT_BY_SCHEMA_LABEL,
+  STATIC_SCHEMA_TYPE,
+  TYPES_SECTION_TYPE,
+  TYPE_COLLECTION_TYPE,
+  buildViewIndex,
+  createObjectNode,
+  downloadBlob,
+  getDynamicLabel,
+} from './shared';
+
+//
+// Extension Factory
+//
+
+/** Creates database extensions: types section, schema nodes, schema children, and schema actions. */
+export const createDatabaseExtensions = Effect.fnUntraced(function* () {
+  const capabilities = yield* Capability.Service;
+
+  return yield* Effect.all([
+    // Types section virtual node under each space.
+    GraphBuilder.createExtension({
+      id: 'typesSection',
+      match: AppNodeMatcher.whenSpace,
+      connector: (space, get) => {
+        const spaceState = get(CreateAtom.fromObservable(space.state));
+        if (spaceState !== SpaceState.SPACE_READY) {
+          return Effect.succeed([]);
+        }
+
+        return Effect.succeed([
+          AppNode.makeSection({
+            id: Segments.types,
+            type: TYPES_SECTION_TYPE,
+            label: ['types-section.label', { ns: meta.id }],
+            icon: 'ph--database--regular',
+            space,
+            position: 'last',
+            testId: 'spacePlugin.typesSection',
+          }),
+        ]);
+      },
+    }),
+
+    // Schema nodes under the Types virtual node.
+    GraphBuilder.createExtension({
+      id: 'types',
+      match: (node) => {
+        const space = isSpace(node.properties.space) ? node.properties.space : undefined;
+        return node.type === TYPES_SECTION_TYPE && space ? Option.some(space) : Option.none();
+      },
+      connector: (space, get) => {
+        // Persisted types live in the space db; static/runtime types live in the shared registry.
+        // Fan across both so the space's own types appear without leaking other spaces' types.
+        const allSchemas = get(
+          space.db.query(Query.select(Filter.type(Type.Type)).from(Scope.space(), Scope.registry())).atom,
+        );
+
+        const userSchemas = allSchemas.filter((type) => {
+          if (Type.isRelation(type)) {
+            return false;
+          }
+          if (Type.isTypeKind(type)) {
+            return false;
+          }
+          const schema = Type.getSchema(type);
+          if (HiddenAnnotation.get(schema).pipe(Option.getOrElse(() => false))) {
+            return false;
+          }
+          if (Type.getTypename(type) === Type.getTypename(Collection.Collection)) {
+            return false;
+          }
+          return true;
+        });
+
+        const viewIndex = buildViewIndex(get, space, allSchemas);
+
+        const visibleSchemas = userSchemas.filter((schema) => {
+          if (Type.getDatabase(schema) != null) {
+            return true;
+          }
+          const typeUri = Type.getURI(schema);
+          const objects = get(space.db.query(Filter.type(typeUri)).atom);
+          if (ViewAnnotation.has(schema)) {
+            return objects.some((obj) => !viewIndex.isView(obj));
+          }
+          return objects.length > 0 || viewIndex.typeUrisWithViews.has(typeUri);
+        });
+
+        return Effect.succeed(visibleSchemas.map((schema) => createSchemaNode({ schema, space, get })));
+      },
+    }),
+
+    // {All} virtual node + view objects under each schema node.
+    GraphBuilder.createExtension({
+      id: 'schemaChildren',
+      match: (node) => {
+        const space = isSpace(node.properties.space) ? node.properties.space : undefined;
+        return space && Type.isType(node.data) ? Option.some({ space, schema: node.data }) : Option.none();
+      },
+      connector: ({ space, schema }, get) => {
+        const client = get(capabilities.atom(ClientCapabilities.Client)).at(0);
+        const schemas = client ? get(client.graph.registry.query(Filter.type(Type.Type)).atom) : [];
+
+        const slug = getTypeSlug(schema);
+        const typeUri = Type.getURI(schema);
+
+        // {All} virtual node.
+        const allNode = Node.make({
+          id: 'all',
+          type: TYPE_COLLECTION_TYPE,
+          data: { space, typeUri },
+          properties: {
+            label: ['type-collection-all.label', { ns: meta.id }],
+            icon: 'ph--list--regular',
+            iconHue: 'neutral',
+            role: 'branch',
+            testId: `spacePlugin.typeCollectionAll.${slug}`,
+            selectable: false,
+            draggable: false,
+            droppable: false,
+            childrenDroppable: false,
+            blockInstruction: BLOCK_REORDER_ABOVE,
+          },
+        });
+
+        // View objects for this schema.
+        const viewIndex = buildViewIndex(get, space, schemas);
+        const viewNodes = viewIndex
+          .getViewsForTypeUri(typeUri)
+          .map((object: Obj.Unknown) =>
+            createObjectNode({
+              db: space.db,
+              object,
+              droppable: false,
+            }),
+          )
+          .filter(isNonNullable);
+
+        return Effect.succeed([allNode, ...viewNodes]);
+      },
+    }),
+
+    // Objects of the schema type under the {All} node.
+    GraphBuilder.createExtension({
+      id: 'typeCollectionObjects',
+      match: (node) => {
+        if (node.type !== TYPE_COLLECTION_TYPE || !node.data?.space || !node.data?.typeUri) {
+          return Option.none();
+        }
+        return Option.some({ space: node.data.space as Space, typeUri: node.data.typeUri as URI.URI });
+      },
+      connector: ({ space, typeUri }, get) => {
+        const client = get(capabilities.atom(ClientCapabilities.Client)).at(0);
+        const schemas = client ? get(client.graph.registry.query(Filter.type(Type.Type)).atom) : [];
+        const viewIndex = buildViewIndex(get, space, schemas);
+        const objects = get(space.db.query(Filter.type(typeUri)).atom).filter(
+          (object: Obj.Unknown) => !viewIndex.isView(object) && !Obj.getParent(object),
+        );
+
+        return Effect.succeed(
+          objects
+            .map((object: Obj.Unknown) => {
+              get(Obj.atom(object));
+              return createObjectNode({
+                db: space.db,
+                object,
+                droppable: false,
+              });
+            })
+            .filter(isNonNullable)
+            .toSorted((nodeA, nodeB) => {
+              const labelA = typeof nodeA.properties.label === 'string' ? nodeA.properties.label : '';
+              const labelB = typeof nodeB.properties.label === 'string' ? nodeB.properties.label : '';
+              return labelA.localeCompare(labelB);
+            }),
+        );
+      },
+    }),
+
+    // Actions for schema nodes.
+    GraphBuilder.createExtension({
+      id: 'schemaActions',
+      match: (node) => {
+        const space = isSpace(node.properties.space) ? node.properties.space : undefined;
+        return space && Type.isType(node.data) ? Option.some({ space, schema: node.data }) : Option.none();
+      },
+      actions: ({ space, schema }, get) => {
+        const client = get(capabilities.atom(ClientCapabilities.Client)).at(0);
+        const schemas = client ? get(client.graph.registry.query(Filter.type(Type.Type)).atom) : [];
+
+        const targetUri = Type.getURI(schema);
+        const viewIndex = buildViewIndex(get, space, schemas);
+        const deletable = Type.getDatabase(schema) != null && viewIndex.getViewsForTypeUri(targetUri).length === 0;
+
+        return Effect.succeed(createSchemaActions({ type: schema, space, deletable, capabilities }));
+      },
+    }),
+  ]);
+});
+
+//
+// Helpers
+//
+
+/** Returns schemas keyed uniquely by typename, preferring later entries. */
+const uniqueSchemasByTypename = <TSchema extends Type.AnyEntity>(schemas: TSchema[]): TSchema[] => {
+  const uniqueSchemas = new Map<string, TSchema>();
+  for (const schema of schemas) {
+    uniqueSchemas.set(Type.getTypename(schema), schema);
+  }
+
+  return [...uniqueSchemas.values()];
+};
+
+/** Builds a graph node for a schema in the Types subtree. */
+const createSchemaNode = ({
+  schema,
+  space,
+  get,
+}: {
+  schema: Type.AnyEntity;
+  space: Space;
+  get: Atom.Context;
+}): Node.NodeArg<Type.AnyEntity> => {
+  const typename = Type.getTypename(schema);
+  // The node id doubles as the `types/<slug>` path segment, so it must be slash- and colon-free:
+  // a stored schema's entity id, or a static schema's typename.
+  const slug = getTypeSlug(schema);
+  const iconAnnotation =
+    Type.getDatabase(schema) == null
+      ? Option.getOrUndefined(Annotation.IconAnnotation.get(Type.getSchema(schema)))
+      : undefined;
+  const { label, nodeId } = Match.value(schema).pipe(
+    Match.when(
+      (value: Type.AnyEntity) => Type.getDatabase(value) != null,
+      (mutableSchema) => {
+        // Type.AnyEntity has KindId=Type at the type level but is a valid ECHO entity at runtime.
+        const snapshot = get(Entity.atom(mutableSchema as unknown as Entity.Unknown));
+        return {
+          label: (snapshot as { name?: string }).name || [
+            'object-name.placeholder',
+            { ns: Type.getTypename(Type.Type) },
+          ],
+          nodeId: slug,
+        };
+      },
+    ),
+    Match.orElse(() => ({
+      label: getDynamicLabel('typename.label', typename, { count: 2, defaultValue: typename }),
+      nodeId: slug,
+    })),
+  );
+  const icon =
+    Type.getDatabase(schema) != null ? 'ph--cube--regular' : (iconAnnotation?.icon ?? 'ph--circle-dashed--regular');
+  const iconHue = Type.getDatabase(schema) != null ? 'neutral' : iconAnnotation?.hue;
+  return Node.make({
+    id: nodeId,
+    type: STATIC_SCHEMA_TYPE,
+    data: schema,
+    properties: {
+      label,
+      icon,
+      iconHue,
+      role: 'branch',
+      testId: `spacePlugin.schemaNode.${typename}`,
+      selectable: false,
+      draggable: false,
+      droppable: false,
+      childrenDroppable: false,
+      space,
+    },
+  });
+};
+
+/** Builds schema actions (add view, rename, delete, snapshot). */
+const createSchemaActions = ({
+  type,
+  space,
+  deletable,
+  capabilities,
+}: {
+  type: Type.AnyEntity;
+  space: Space;
+  deletable: boolean;
+  capabilities: CapabilityManager.CapabilityManager;
+}) => {
+  const typename = Type.getTypename(type);
+  const createEntry = capabilities
+    .getAll(SpaceCapabilities.CreateObjectEntry)
+    .find((entry: SpaceCapabilities.CreateObjectEntry) => entry.id === typename);
+
+  // For database-persisted object schemas without a dedicated capability, synthesize a generic entry.
+  const resolvedEntry: SpaceCapabilities.CreateObjectEntry | undefined =
+    createEntry ??
+    (Type.getDatabase(type) != null && Type.isObject(type) ? makeCreateObjectEntryForDatabaseType(type) : undefined);
+  const createObjectFn = resolvedEntry?.createObject;
+  const inputSchema = resolvedEntry?.inputSchema;
+
+  const actions: Node.NodeArg<Node.ActionData<Operation.Service>>[] = [
+    ...(createObjectFn
+      ? [
+          Node.makeAction({
+            id: SpaceOperation.OpenCreateObject.meta.key,
+            data: Effect.fnUntraced(function* () {
+              if (inputSchema) {
+                yield* Operation.invoke(SpaceOperation.OpenCreateObject, {
+                  target: space.db,
+                  typename,
+                });
+              } else {
+                const result = yield* createObjectFn({}, { db: space.db, target: space.db }).pipe(
+                  Effect.provideService(Capability.Service, capabilities),
+                );
+                if (result.subject.length > 0) {
+                  yield* Operation.invoke(LayoutOperation.Open, {
+                    subject: [...result.subject],
+                    navigation: 'immediate',
+                  });
+                }
+              }
+            }),
+            properties: {
+              // Static plugin types carry a per-typename `add-object.label` (e.g. "Add event");
+              // database types have no such namespace, so fall back to the plugin's generic label.
+              label: getDynamicLabel('add-object.label', Type.getDatabase(type) != null ? meta.id : typename),
+              icon: 'ph--plus--regular',
+              disposition: 'list-item-primary',
+              testId: 'spacePlugin.createObject',
+            },
+          }),
+        ]
+      : []),
+    Node.makeAction({
+      id: `${SpaceOperation.AddObject.meta.key}-view`,
+      data: () =>
+        Operation.invoke(SpaceOperation.OpenCreateObject, {
+          target: space.db,
+          views: true,
+          initialFormValues: { typename: Type.getTypename(type) },
+        }),
+      properties: {
+        label: ADD_VIEW_TO_SCHEMA_LABEL,
+        icon: 'ph--circles-three-plus--regular',
+        disposition: 'list-item',
+        testId: 'spacePlugin.addViewToSchema',
+      },
+    }),
+    Node.makeAction({
+      id: SpaceOperation.RenameObject.meta.key,
+      data: (params?: Node.InvokeProps) =>
+        Type.getDatabase(type) != null
+          ? Operation.invoke(SpaceOperation.RenameObject, {
+              object: type,
+              caller: `${params?.caller}:${params?.parent?.id}`,
+            })
+          : Effect.fail(new Error('Cannot rename immutable schema')),
+      properties: {
+        label: getDynamicLabel('rename-object.label', Type.getTypename(Type.Type)),
+        icon: 'ph--pencil-simple-line--regular',
+        disabled: Type.getDatabase(type) == null,
+        disposition: 'list-item',
+        testId: 'spacePlugin.renameObject',
+      },
+    }),
+    Node.makeAction({
+      id: SpaceOperation.RemoveObjects.meta.key,
+      data: () =>
+        Type.getDatabase(type) != null
+          ? Operation.invoke(SpaceOperation.RemoveObjects, {
+              objects: [type],
+            })
+          : Effect.succeed(undefined),
+      properties: {
+        label: getDynamicLabel('delete-object.label', Type.getTypename(Type.Type)),
+        icon: 'ph--trash--regular',
+        disposition: 'list-item',
+        disabled: !deletable,
+        testId: 'spacePlugin.deleteObject',
+      },
+    }),
+    Node.makeAction({
+      id: SpaceOperation.Snapshot.meta.key,
+      data: Effect.fnUntraced(function* () {
+        const result = yield* Operation.invoke(SpaceOperation.Snapshot, {
+          db: space.db,
+          query: Query.select(Filter.type(type)).ast,
+        });
+        if (result.snapshot) {
+          yield* Effect.tryPromise(() =>
+            downloadBlob(result.snapshot, createFilename({ parts: [space.id, Type.getTypename(type)], ext: 'json' })),
+          );
+        }
+      }),
+      properties: {
+        label: SNAPSHOT_BY_SCHEMA_LABEL,
+        icon: 'ph--camera--regular',
+        disposition: 'list-item',
+      },
+    }),
+  ];
+
+  return actions;
+};

package/src/capabilities/app-graph-builder/extensions/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { createSpaceExtensions } from './spaces';
+export { createDatabaseExtensions } from './database';
+export { createCollectionExtensions } from './collections';
+export { createCompanionExtensions } from './companions';
+export { createSettingsExtensions } from './settings';

package/src/capabilities/app-graph-builder/extensions/settings.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { AppNode, AppNodeMatcher, isPersonalSpace } from '@dxos/app-toolkit';
+import { GraphBuilder, Node } from '@dxos/plugin-graph';
+
+import { meta } from '#meta';
+import { SETTINGS_SECTION_ID, SETTINGS_SECTION_TYPE } from '#types';
+
+//
+// Extension Factory
+//
+
+/**
+ * Settings section attached directly under each Space node, plus its children.
+ *
+ * The virtual `settings` section is pinned to the top via `position: 'first'`
+ * so it sits above the un-positioned middle band (collections, mailboxes,
+ * automations, integrations, etc.). It groups the panels contributed by this
+ * plugin (general, members) and by other plugins (automation, functions).
+ */
+export const createSettingsExtensions = Effect.fnUntraced(function* () {
+  const sectionExtension = yield* GraphBuilder.createExtension({
+    id: 'settingsSection',
+    match: AppNodeMatcher.whenSpace,
+    connector: (space) =>
+      Effect.succeed([
+        AppNode.makeSection({
+          id: SETTINGS_SECTION_ID,
+          type: SETTINGS_SECTION_TYPE,
+          label: ['settings-section.label', { ns: meta.id }],
+          icon: 'ph--sliders--regular',
+          iconHue: 'indigo',
+          space,
+          position: 'first',
+          testId: 'spacePlugin.settings',
+        }),
+      ]),
+  });
+
+  const childrenExtension = yield* GraphBuilder.createExtension({
+    id: 'settingsSections',
+    match: AppNodeMatcher.whenSpaceSettings,
+    connector: (space) => {
+      const personal = isPersonalSpace(space);
+      return Effect.succeed([
+        Node.make({
+          id: 'general',
+          type: `${meta.id}.general`,
+          data: `${meta.id}.general`,
+          properties: {
+            label: ['space-settings-properties.label', { ns: meta.id }],
+            icon: 'ph--brackets-curly--regular',
+            iconHue: 'indigo',
+            space,
+            testId: 'spacePlugin.general',
+          },
+        }),
+        ...(!personal
+          ? [
+              Node.make({
+                id: 'members',
+                type: `${meta.id}.members`,
+                data: `${meta.id}.members`,
+                properties: {
+                  label: ['members-panel.label', { ns: meta.id }],
+                  icon: 'ph--users--regular',
+                  iconHue: 'indigo',
+                  space,
+                  testId: 'spacePlugin.members',
+                },
+              }),
+            ]
+          : []),
+      ]);
+    },
+  });
+
+  return [sectionExtension, childrenExtension];
+});

package/src/capabilities/app-graph-builder/extensions/shared.test.ts

@@ -0,0 +1,170 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Registry from '@effect-atom/atom/Registry';
+import * as Schema from 'effect/Schema';
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { type Space, SpaceState } from '@dxos/client/echo';
+import { Annotation, DXN, Entity, Filter, Obj, Query, Ref, Type, View } from '@dxos/echo';
+import { type EchoDatabase } from '@dxos/echo-client';
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { MigrationVersionAnnotation, Migrations } from '@dxos/migrations';
+import { ViewAnnotation } from '@dxos/schema';
+
+import { buildViewIndex, checkPendingMigration } from './shared';
+
+const TestContact = Schema.Struct({
+  name: Schema.String,
+}).pipe(Type.makeObject(DXN.make('com.example.type.contact', '0.1.0')));
+
+const TestViewWrapper = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  view: Ref.Ref(View.View),
+}).pipe(ViewAnnotation.set(['view']), Type.makeObject(DXN.make('com.example.type.viewWrapper', '0.1.0')));
+
+describe('buildViewIndex', () => {
+  let testBuilder: EchoTestBuilder;
+  let db: EchoDatabase;
+  let registry: Registry.Registry;
+
+  beforeEach(async () => {
+    testBuilder = await new EchoTestBuilder().open();
+    const result = await testBuilder.createDatabase({ types: [TestContact, TestViewWrapper, View.View] });
+    db = result.db;
+    registry = Registry.make();
+  });
+
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('includes typename when a straightforward view targets it', async ({ expect }) => {
+    const viewObj = db.add(
+      View.make({
+        query: { ast: Query.select(Filter.type(TestContact)).ast },
+      }),
+    );
+    db.add(Obj.make(TestViewWrapper, { view: Ref.make(viewObj) }));
+    await db.flush();
+
+    const allSchemas = db.graph.registry
+      .list()
+      .filter(Type.isType)
+      .filter((t) => !Type.isTypeKind(t));
+    const viewIndex = buildViewIndex(registry.get.bind(registry) as any, { db } as any, allSchemas);
+
+    expect(viewIndex.typeUrisWithViews.has(Type.getURI(TestContact))).toBe(true);
+  });
+
+  test('excludes typename when no straightforward view targets it', async ({ expect }) => {
+    const viewObj = db.add(
+      View.make({
+        query: { ast: Query.select(Filter.nothing()).ast },
+      }),
+    );
+    db.add(Obj.make(TestViewWrapper, { view: Ref.make(viewObj) }));
+    await db.flush();
+
+    const allSchemas = db.graph.registry
+      .list()
+      .filter(Type.isType)
+      .filter((t) => !Type.isTypeKind(t));
+    const viewIndex = buildViewIndex(registry.get.bind(registry) as any, { db } as any, allSchemas);
+
+    expect(viewIndex.typeUrisWithViews.has(Type.getURI(TestContact))).toBe(false);
+    expect(viewIndex.typeUrisWithViews.size).toBe(0);
+  });
+
+  test('getViewsForTypeUri returns matching view objects', async ({ expect }) => {
+    const viewObj = db.add(
+      View.make({
+        query: { ast: Query.select(Filter.type(TestContact)).ast },
+      }),
+    );
+    const tableView = db.add(Obj.make(TestViewWrapper, { view: Ref.make(viewObj) }));
+    await db.flush();
+
+    const allSchemas = db.graph.registry
+      .list()
+      .filter(Type.isType)
+      .filter((t) => !Type.isTypeKind(t));
+    const viewIndex = buildViewIndex(registry.get.bind(registry) as any, { db } as any, allSchemas);
+
+    const views = viewIndex.getViewsForTypeUri(Type.getURI(TestContact));
+    expect(views).toHaveLength(1);
+    expect(views[0].id).toBe(tableView.id);
+  });
+
+  test('returns empty index when no view schemas exist', async ({ expect }) => {
+    await db.flush();
+
+    const userSchemas = db.graph.registry
+      .list()
+      .filter(Type.isType)
+      .filter((t) => !Type.isTypeKind(t))
+      .filter((schema) => !ViewAnnotation.has(schema));
+    const viewIndex = buildViewIndex(registry.get.bind(registry) as any, { db } as any, userSchemas);
+
+    expect(viewIndex.typeUrisWithViews.size).toBe(0);
+    expect(viewIndex.getViewsForTypeUri(Type.getURI(TestContact))).toHaveLength(0);
+  });
+});
+
+describe('checkPendingMigration', () => {
+  const TARGET = '1970-01-02';
+
+  // Minimal fake exercising only the fields checkPendingMigration reads (state, properties).
+  // Must pass isEntity (checks for Entity.KindId) and have Obj.Meta so Annotation.get works.
+  const makeFakeProperties = (version?: string): Record<string | symbol, unknown> => {
+    const annotations: Record<string, unknown> = {};
+    if (version !== undefined) {
+      Annotation.setDictionary(annotations as any, MigrationVersionAnnotation, version);
+    }
+    return {
+      [Entity.KindId]: Entity.Kind.Object,
+      [Obj.Meta]: { keys: [], annotations },
+    };
+  };
+
+  const makeFakeSpace = (state: SpaceState, version?: string): Space =>
+    ({ state: { get: () => state }, properties: makeFakeProperties(version) }) as unknown as Space;
+
+  let savedNamespace: string | undefined;
+  let savedMigrations: typeof Migrations.migrations;
+
+  beforeEach(() => {
+    savedNamespace = Migrations.namespace;
+    savedMigrations = Migrations.migrations;
+    Migrations.define('test', [
+      { version: '1970-01-01', next: async () => {} },
+      { version: TARGET, next: async () => {} },
+    ]);
+  });
+
+  afterEach(() => {
+    Migrations.namespace = savedNamespace;
+    Migrations.migrations = savedMigrations;
+  });
+
+  test('SPACE_REQUIRES_MIGRATION is pending regardless of version property', ({ expect }) => {
+    const space = makeFakeSpace(SpaceState.SPACE_REQUIRES_MIGRATION, TARGET);
+    expect(checkPendingMigration(space)).toBe(true);
+  });
+
+  test('READY with version matching target is not pending', ({ expect }) => {
+    const space = makeFakeSpace(SpaceState.SPACE_READY, TARGET);
+    expect(checkPendingMigration(space)).toBe(false);
+  });
+
+  test('READY with undefined version is pending (legacy property-migration preserved)', ({ expect }) => {
+    const space = makeFakeSpace(SpaceState.SPACE_READY);
+    expect(checkPendingMigration(space)).toBe(true);
+  });
+
+  test('READY with stale version is pending', ({ expect }) => {
+    const space = makeFakeSpace(SpaceState.SPACE_READY, '1970-01-01');
+    expect(checkPendingMigration(space)).toBe(true);
+  });
+});