@openchambery/web 2.0.0-beta.4 → 2.0.0-beta.5

package/server/lib/opencode/upgrade-screen.test.js

@@ -0,0 +1,196 @@
+import express from 'express';
+import request from 'supertest';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  REQUIRED_OPENCODE_VERSION,
+  describeUpgradeScreen,
+  evaluateUpgradeScreenInstallResult,
+  installRequiredOpenCode,
+  registerUpgradeScreenRoutes,
+  resolveUpgradeScreenTarget,
+} from './upgrade-screen.js';
+
+describe('upgrade screen version gate', () => {
+  it('uses 2.0.15 even when the runtime pin is older', () => {
+    expect(REQUIRED_OPENCODE_VERSION).toBe('2.0.15');
+    expect(resolveUpgradeScreenTarget('2.0.12')).toBe('2.0.15');
+    expect(resolveUpgradeScreenTarget('2.0.16')).toBe('2.0.16');
+  });
+
+  it('does not open the gate at or above 2.0.15', () => {
+    expect(describeUpgradeScreen({
+      version: '2.0.15',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'compatible', canInstall: false, minimumVersion: '2.0.15' });
+    expect(describeUpgradeScreen({
+      version: 'v2.0.16',
+      installation: 'managed',
+      platformCanInstall: true,
+    }).state).toBe('compatible');
+  });
+
+  it('opens the gate below 2.0.15 and offers install only when this runtime can switch', () => {
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true, version: '2.0.14' });
+    expect(describeUpgradeScreen({
+      version: '1.18.30',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true });
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'external',
+      platformCanInstall: true,
+    }).canInstall).toBe(false);
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'bundled',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true, installation: 'bundled' });
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'managed',
+      platformCanInstall: false,
+    }).canInstall).toBe(false);
+  });
+
+  it('does not treat a missing version as an old install', () => {
+    expect(describeUpgradeScreen({
+      version: null,
+      installation: 'managed',
+      platformCanInstall: true,
+    }).state).toBe('unavailable');
+  });
+
+  it('does not report an unverified install as upgraded', () => {
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.15',
+      serveVersion: '2.0.14',
+    })).toMatchObject({ ok: false, upgraded: false, version: '2.0.14' });
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.15',
+      serveVersion: null,
+    }).upgraded).toBe(false);
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.15',
+      serveVersion: '2.0.15',
+    })).toMatchObject({ ok: true, upgraded: true, version: '2.0.15' });
+  });
+});
+
+describe('installRequiredOpenCode', () => {
+  const createDeps = (overrides = {}) => {
+    const calls = [];
+    const deps = {
+      resolveOwnership: async () => ({ ownership: 'global-cli', guidance: null }),
+      readServeVersion: async () => '2.0.14',
+      readCliVersion: () => '2.0.14',
+      platformCanInstall: true,
+      install: vi.fn(async () => {
+        calls.push('install');
+        return '/cache/opencode';
+      }),
+      readBinaryVersion: vi.fn(() => '2.0.15'),
+      persistBinary: vi.fn(async () => {
+        calls.push('persist');
+      }),
+      forceBinary: vi.fn(() => {
+        calls.push('force');
+      }),
+      restart: vi.fn(async () => {
+        calls.push('restart');
+      }),
+      waitReady: vi.fn(async () => {
+        calls.push('ready');
+      }),
+      readConfiguredBinary: async () => null,
+      isSharedService: () => false,
+      ...overrides,
+    };
+    return { deps, calls };
+  };
+
+  it('installs 2.0.15 and only succeeds after the running serve is verified', async () => {
+    const { deps, calls } = createDeps({
+      readServeVersion: vi.fn()
+        .mockResolvedValueOnce('2.0.14')
+        .mockResolvedValueOnce('2.0.15'),
+    });
+
+    await expect(installRequiredOpenCode(deps)).resolves.toMatchObject({
+      ok: true,
+      upgraded: true,
+      version: '2.0.15',
+      targetVersion: '2.0.15',
+    });
+    expect(deps.install).toHaveBeenCalledWith({ version: '2.0.15' });
+    expect(calls).toEqual(['install', 'persist', 'force', 'restart', 'ready']);
+  });
+
+  it('returns the failure reason and does not claim an upgrade when verification fails', async () => {
+    const { deps } = createDeps({
+      readServeVersion: vi.fn()
+        .mockResolvedValueOnce('1.18.30')
+        .mockResolvedValueOnce('1.18.30'),
+      readCliVersion: () => '1.18.30',
+      readBinaryVersion: () => '2.0.15',
+    });
+
+    await expect(installRequiredOpenCode(deps)).rejects.toThrow(/still 1\.18\.30/);
+    expect(deps.persistBinary).toHaveBeenCalledWith('');
+  });
+
+  it('does not install when the runtime cannot switch', async () => {
+    const { deps } = createDeps({
+      resolveOwnership: async () => ({
+        ownership: 'external-serve',
+        guidance: 'Restart that server yourself.',
+      }),
+    });
+
+    await expect(installRequiredOpenCode(deps)).rejects.toMatchObject({
+      status: 409,
+      message: 'Restart that server yourself.',
+    });
+    expect(deps.install).not.toHaveBeenCalled();
+  });
+});
+
+describe('upgrade screen routes', () => {
+  it('hides the gate for 2.0.15 and reports install failure without upgraded:true', async () => {
+    const app = express();
+    app.use(express.json());
+    const readServeVersion = vi.fn()
+      .mockResolvedValueOnce('2.0.15')
+      .mockResolvedValueOnce('2.0.12')
+      .mockResolvedValueOnce('2.0.12');
+    registerUpgradeScreenRoutes(app, {
+      resolveOwnership: async () => ({ ownership: 'owned-cache', guidance: null }),
+      readServeVersion,
+      readCliVersion: () => '2.0.12',
+      platformCanInstall: true,
+      install: vi.fn(async () => {
+        throw new Error('registry unreachable');
+      }),
+      readBinaryVersion: () => '2.0.15',
+      persistBinary: vi.fn(),
+      forceBinary: vi.fn(),
+      restart: vi.fn(),
+    });
+
+    const compatible = await request(app).get('/api/opencode/compatibility').expect(200);
+    expect(compatible.body).toMatchObject({ state: 'compatible', version: '2.0.15', minimumVersion: '2.0.15' });
+
+    const failed = await request(app).post('/api/opencode/install-required').expect(500);
+    expect(failed.body).toMatchObject({
+      success: false,
+      upgraded: false,
+      error: 'registry unreachable',
+    });
+    expect(failed.body.upgraded).not.toBe(true);
+  });
+});

package/server/lib/session-metadata/DOCUMENTATION.md

@@ -1,32 +1,42 @@
 # Session metadata store
 
-OpenChamber-owned per-session metadata for Host features that used to live on
-OpenCode `session.metadata`.
+OpenChamber session metadata whose durable copy lives on the OpenCode session
+record. The side JSON file is the cache and the pre-migration source.
 
 ## Why
 
-Session goal progress, Host archive stamps, and later other Host state under the
-`openchamber` namespace are OpenChamber product state. The Host owns their
-authority: it serializes conditional writes, publishes only persisted values,
-and protects archive fields from generic patches. They therefore live in this
-Host store and are folded back onto proxy session list/detail/SSE responses so
-clients still read `session.metadata` and `time.archived`.
+Session goal progress, Host archive stamps, titles, and other Host state under
+the `openchamber` namespace travel with the OpenCode session. `session.update`
+(`PATCH /api/session/:id`, body `{ title?, metadata?, permissions? }`) replaces
+`metadata` wholesale. Archive is `metadata.openchamber.archive.archivedAt` on
+that record and is still projected onto `time.archived`. Title is the record's
+`title` field and is not sent when only metadata changes.
 
-Upstream capability is tracked per version and does not change that ownership:
+`opencode-session-record.js` is the only module that knows that call. A client
+whose types omit `session.update` metadata still goes through that module;
+a missing API throws and is never an empty write.
+
+The side file remains until each row has been copied or OpenCode has confirmed
+the session is gone. Until that load succeeds, the file is not an authoritative
+empty catalog: a failed read stays unwritable and does not clear other sessions.
+A session OpenCode still has is listed even when the side file has no row.
+One failed copy does not delete the other rows or the other OpenCode sessions.
+
+Fork-specific fields (`goal`, `assistant`, `scheduledTask`, `llm`, `smallModel`,
+and the rest of `openchamber`) are merged onto the record. They are not dropped
+to match a narrower upstream metadata shape.
 
 | OpenCode client | Session metadata update |
 |---|---|
 | Earlier 2.x releases used during the migration | `metadata` accepted at create time only |
-| 2.0.14 | `PATCH /api/session/:id` with body `{ title, metadata, permissions }` (`session.update`) |
-
-Adopting the upstream update API for Host-owned fields requires a separate
-decision about authority, conditional writes, and archive protection.
+| 2.0.14+ / 2.0.15 | `PATCH /api/session/:id` with body `{ title, metadata, permissions }` (`session.update`) |
 
 ## Layout
 
 | File | Role |
 |---|---|
-| `session-metadata-store.js` | Durable store: one JSON file per data dir, `{ [sessionID]: metadata }`, RFC 7386 merge patch, full RMW serialization, refuse-failed-read refuses write/read-as-empty |
+| `opencode-session-record.js` | Read/write title and metadata on the OpenCode session record; migrate the side file without treating a failed load as empty or dropping other sessions |
+| `session-metadata-store.js` | Side-file cache and migration source: `{ [sessionID]: metadata }`, RFC 7386 merge patch, full RMW serialization, refuse-failed-read refuses write/read-as-empty. When a record reader/writer is wired, commits the merged object onto the OpenCode session first |
 | `session-projection.js` | Pure Host authority projection (metadata deep-merge + archive → `time.archived`) |
 | `session-archive.js` | Domain archive/unarchive: validate upstream session + directory, persist, project, best-effort index/broadcast |
 | `system-session.js` | Isolation patches for system session creators: `buildScheduledTaskMetadata`, `buildLlmSessionMetadata`, `buildAssistantSessionMetadata`. Title prefixes are labels and never ownership. |
@@ -59,19 +69,19 @@ decision about authority, conditional writes, and archive protection.
 
 Wired from `packages/web/server/index.js` + `feature-routes-runtime.js`:
 
-1. `createSessionMetadataStore({ dataDir: OPENCHAMBER_DATA_DIR })` + initial `load()`
+1. `createHttpSessionRecordClient` + `createSessionMetadataStore({ dataDir, recordReader, recordWriter })` + initial `load()`, then `startSideStoreMigration`
 2. proxy `getStoredSessionMetadata` / `getStoredSessionMetadataSync` → list/get + direct SSE overlay
 3. global hub `projectOutboundSessionPayload` → live + replay session lifecycle authority
 4. session-index sync `projectSessions` + event-ingest `projectSession` / `onSessionDeleted`
 5. `createSessionArchiveService` after session index exists
 6. session-goal `readSessionMetadata` / `mutateSessionMetadata` / `persistSessionGoal`
 7. `registerSessionMetadataRoutes` (metadata + archive)
-8. assistants `archiveSessionHost` → shared Host archive (not upstream `session.update`)
+8. assistants `archiveSessionHost` → shared Host archive, which write-throughs `metadata` onto the OpenCode session record without clearing `title`
 9. system session creators persist isolation through `persistSessionMetadata`
    (`setSessionMetadata` + `openchamber:session-metadata` broadcast) and then
    `onSystemSessionPersisted` (index upsert that removes the row). Wired from
    `index.js` into scheduled-task runtime, LLM attachment generate, and
-   Assistant binding create. OpenCode create-time `metadata` is a hint only.
+   Assistant binding create. Create-time `metadata` is merged onto the session record; it is not a second authority.
 
 Capability is open (`supported: true`). Manual UI metadata writes, session-goal
 routes, and scheduled-task goal create all persist `openchamber.goal` through

package/server/lib/session-metadata/opencode-session-record.d.ts

@@ -0,0 +1,57 @@
+export function mergeOwnedMetadata(
+  openCodeMetadata: unknown,
+  sideMetadata: unknown,
+): Record<string, unknown>;
+
+export function writeSessionRecordViaClient(
+  client: { session?: { update?: (input: unknown, requestOptions?: unknown) => Promise<unknown> } } | null | undefined,
+  input: {
+    sessionID: string;
+    metadata?: Record<string, unknown>;
+    title?: string;
+    requestOptions?: object;
+  },
+): Promise<void>;
+
+export function readSessionRecordViaClient(
+  client: { session?: { get?: (input: unknown, requestOptions?: unknown) => Promise<unknown> } } | null | undefined,
+  input: { sessionID: string; requestOptions?: object },
+): Promise<Record<string, unknown> | null>;
+
+export function createHttpSessionRecordClient(options: {
+  buildSessionUrl: (sessionID: string, directory?: string | null) => string;
+  getHeaders?: () => Record<string, string>;
+  fetchFn?: typeof fetch;
+}): {
+  read: (sessionID: string, directory?: string | null) => Promise<Record<string, unknown> | null>;
+  write: (input: {
+    sessionID: string;
+    metadata?: Record<string, unknown>;
+    title?: string;
+    directory?: string | null;
+  }) => Promise<void>;
+};
+
+export function migrateLoadedSideStore(input: {
+  loadResult: { ok?: boolean; entries?: Record<string, object> | null } | null;
+  readSession: (sessionID: string) => Promise<object | null>;
+  writeMetadata: (sessionID: string, metadata: object, record: object) => Promise<void>;
+}): Promise<{
+  status: 'unavailable' | 'partial' | 'complete';
+  migrated: string[];
+  failed: Array<{ id: string; error: string }>;
+  absent: string[];
+}>;
+
+export function retainOpenCodeSessions(
+  openCodeSessions: unknown,
+  sideById: Record<string, object> | null | undefined,
+): unknown[];
+
+export function startSideStoreMigration(options: {
+  load: () => Promise<{ ok?: boolean; entries?: Record<string, object> }>;
+  readSession: (sessionID: string) => Promise<object | null>;
+  writeMetadata: (sessionID: string, metadata: object, record: object) => Promise<void>;
+  setTimer?: typeof setTimeout;
+  clearTimer?: typeof clearTimeout;
+}): () => void;

package/server/lib/session-metadata/opencode-session-record.js

@@ -0,0 +1,316 @@
+/**
+ * OpenCode session-record ownership for OpenChamber metadata.
+ *
+ * OpenCode 2.0.15 `PATCH /api/session/:id` (`session.update`) replaces
+ * `metadata` wholesale and can set `title`. Archive stays in
+ * `metadata.openchamber.archive` on that same record, then projects onto
+ * `time.archived`. This module is the only place that knows that call.
+ *
+ * A client whose types do not yet expose `session.update` metadata still goes
+ * through `writeSessionRecordViaClient` / `createHttpSessionRecordClient`.
+ * Missing the API throws — it is never an empty success.
+ *
+ * The side store is a migration source. A failed load is not an empty catalog.
+ * One session's migration failure does not delete other sessions or their rows.
+ */
+
+import { mergeOwnedMetadata, projectSessionWithStoredMap } from './session-projection.js';
+
+export { mergeOwnedMetadata };
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const asNonEmptyString = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+const isSessionNotFoundError = (error) => {
+  const status = Number(error?.status ?? error?.statusCode);
+  if (status === 404) return true;
+  const tag = error?._tag || error?.name;
+  return tag === 'SessionNotFoundError' || tag === 'Session.NotFoundError';
+};
+
+const deepEqual = (left, right) => {
+  if (left === right) return true;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false;
+    return left.every((item, index) => deepEqual(item, right[index]));
+  }
+  if (!isPlainObject(left) || !isPlainObject(right)) return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) return false;
+  return leftKeys.every((key) => deepEqual(left[key], right[key]));
+};
+
+const unwrapSession = (payload) => {
+  if (!isPlainObject(payload)) return null;
+  if (isPlainObject(payload.data) && typeof payload.data.id === 'string') return payload.data;
+  if (typeof payload.id === 'string') return payload;
+  return null;
+};
+
+/**
+ * Structural adapter for `@opencode/client` session.update.
+ * Throws when the method is absent — never pretends the write landed.
+ *
+ * @param {{ session?: { update?: Function } } | null | undefined} client
+ * @param {{ sessionID: string, metadata?: object, title?: string, requestOptions?: object }} input
+ */
+export const writeSessionRecordViaClient = async (client, input) => {
+  const update = client?.session?.update;
+  if (typeof update !== 'function') {
+    const error = new Error('session.update is unavailable');
+    error.code = 'session_update_unavailable';
+    throw error;
+  }
+  const sessionID = asNonEmptyString(input?.sessionID);
+  if (!sessionID) throw new Error('a session id is required to update the OpenCode session record');
+  const body = { sessionID };
+  if (input.metadata !== undefined) body.metadata = input.metadata;
+  if (input.title !== undefined) body.title = input.title;
+  await update(body, input.requestOptions);
+};
+
+/**
+ * @param {{ session?: { get?: Function } } | null | undefined} client
+ * @param {{ sessionID: string, requestOptions?: object }} input
+ * @returns {Promise<object | null>} null only when OpenCode confirms the session is gone
+ */
+export const readSessionRecordViaClient = async (client, input) => {
+  const get = client?.session?.get;
+  if (typeof get !== 'function') {
+    const error = new Error('session.get is unavailable');
+    error.code = 'session_get_unavailable';
+    throw error;
+  }
+  const sessionID = asNonEmptyString(input?.sessionID);
+  if (!sessionID) throw new Error('a session id is required to read the OpenCode session record');
+  try {
+    const session = await get({ sessionID }, input.requestOptions);
+    return unwrapSession(session) || (isPlainObject(session) ? session : null);
+  } catch (error) {
+    if (isSessionNotFoundError(error)) return null;
+    throw error;
+  }
+};
+
+/**
+ * HTTP owner of `GET` / `PATCH /api/session/:id`. Callers supply the URL so
+ * web and VS Code keep their own prefix rules.
+ *
+ * @param {{
+ *   buildSessionUrl: (sessionID: string, directory?: string | null) => string,
+ *   getHeaders?: () => Record<string, string>,
+ *   fetchFn?: typeof fetch,
+ * }} options
+ */
+export const createHttpSessionRecordClient = ({
+  buildSessionUrl,
+  getHeaders = () => ({}),
+  fetchFn = null,
+}) => {
+  if (typeof buildSessionUrl !== 'function') {
+    throw new Error('createHttpSessionRecordClient requires buildSessionUrl');
+  }
+
+  const request = async (sessionID, { method, directory, body }) => {
+    const fetchImpl = fetchFn || globalThis.fetch;
+    const id = asNonEmptyString(sessionID);
+    if (!id) throw new Error('a session id is required');
+    const url = buildSessionUrl(id, directory);
+    const response = await fetchImpl(url, {
+      method,
+      headers: {
+        Accept: 'application/json',
+        ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        ...(typeof getHeaders === 'function' ? getHeaders() : {}),
+      },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    return response;
+  };
+
+  const read = async (sessionID, directory) => {
+    const response = await request(sessionID, { method: 'GET', directory });
+    if (response.status === 404) return null;
+    if (!response.ok) {
+      const error = new Error(`OpenCode session.get failed (${response.status})`);
+      error.status = response.status;
+      throw error;
+    }
+    const payload = await response.json().catch(() => null);
+    const session = unwrapSession(payload);
+    if (!session) {
+      const error = new Error('OpenCode session.get returned an unreadable record');
+      error.status = 502;
+      throw error;
+    }
+    return session;
+  };
+
+  const write = async ({ sessionID, directory, metadata, title } = {}) => {
+    const body = {};
+    if (metadata !== undefined) body.metadata = metadata;
+    if (title !== undefined) body.title = title;
+    if (Object.keys(body).length === 0) {
+      throw new Error('session record write requires metadata or title');
+    }
+    const response = await request(sessionID, { method: 'PATCH', directory, body });
+    if (response.status === 404) {
+      const error = new Error(`session ${sessionID} was not found`);
+      error.status = 404;
+      throw error;
+    }
+    if (!response.ok) {
+      const error = new Error(`OpenCode session.update failed (${response.status})`);
+      error.status = response.status;
+      throw error;
+    }
+  };
+
+  return { read, write };
+};
+
+/**
+ * Copy side-store rows onto OpenCode records. Refuses a failed load instead of
+ * treating it as an empty catalog. A failed session is reported and skipped;
+ * other sessions, including ones OpenCode has and the side store does not, are
+ * left in place.
+ *
+ * @param {{
+ *   loadResult: { ok?: boolean, entries?: Record<string, object> | null } | null,
+ *   readSession: (sessionID: string) => Promise<object | null>,
+ *   writeMetadata: (sessionID: string, metadata: object, record: object) => Promise<void>,
+ * }} input
+ */
+export const migrateLoadedSideStore = async ({ loadResult, readSession, writeMetadata }) => {
+  if (!loadResult || loadResult.ok !== true || !isPlainObject(loadResult.entries)) {
+    return { status: 'unavailable', migrated: [], failed: [], absent: [] };
+  }
+  if (typeof readSession !== 'function' || typeof writeMetadata !== 'function') {
+    throw new Error('side-store migration requires readSession and writeMetadata');
+  }
+
+  const migrated = [];
+  const failed = [];
+  const absent = [];
+
+  for (const [sessionID, sideMetadata] of Object.entries(loadResult.entries)) {
+    if (!isPlainObject(sideMetadata)) continue;
+    try {
+      const record = await readSession(sessionID);
+      if (record == null) {
+        absent.push(sessionID);
+        continue;
+      }
+      const merged = mergeOwnedMetadata(record.metadata, sideMetadata);
+      if (!deepEqual(merged, isPlainObject(record.metadata) ? record.metadata : {})) {
+        await writeMetadata(sessionID, merged, record);
+      }
+      migrated.push(sessionID);
+    } catch (error) {
+      failed.push({
+        id: sessionID,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return {
+    status: failed.length > 0 ? 'partial' : 'complete',
+    migrated,
+    failed,
+    absent,
+  };
+};
+
+/**
+ * Membership comes from OpenCode. A missing side-store row does not drop the
+ * session. A null side map is an unread store, not an empty catalog.
+ *
+ * @param {unknown} openCodeSessions
+ * @param {Record<string, object> | null | undefined} sideById
+ */
+export const retainOpenCodeSessions = (openCodeSessions, sideById) => {
+  if (!Array.isArray(openCodeSessions)) {
+    throw new Error('OpenCode session list is unavailable');
+  }
+  if (sideById == null || typeof sideById !== 'object' || Array.isArray(sideById)) {
+    throw new Error('session metadata is unavailable');
+  }
+  return openCodeSessions.map((session) => projectSessionWithStoredMap(session, sideById));
+};
+
+const MIGRATION_RETRY_MS = 2_000;
+
+/**
+ * Retry until every loaded side-store row is copied or confirmed absent.
+ * A failed load schedules another attempt and does not write empty metadata.
+ *
+ * @param {{
+ *   load: () => Promise<{ ok?: boolean, entries?: Record<string, object> }>,
+ *   readSession: (sessionID: string) => Promise<object | null>,
+ *   writeMetadata: (sessionID: string, metadata: object, record: object) => Promise<void>,
+ *   setTimer?: typeof setTimeout,
+ *   clearTimer?: typeof clearTimeout,
+ * }} options
+ * @returns {() => void} stop
+ */
+export const startSideStoreMigration = ({
+  load,
+  readSession,
+  writeMetadata,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+}) => {
+  const finished = new Set();
+  let stopped = false;
+  let timer = null;
+
+  const schedule = () => {
+    if (stopped || timer) return;
+    timer = setTimer(() => {
+      timer = null;
+      void attempt();
+    }, MIGRATION_RETRY_MS);
+  };
+
+  const attempt = async () => {
+    if (stopped) return;
+    let loadResult;
+    try {
+      loadResult = await load();
+    } catch {
+      schedule();
+      return;
+    }
+    if (!loadResult || loadResult.ok !== true || !isPlainObject(loadResult.entries)) {
+      schedule();
+      return;
+    }
+    const pending = {};
+    for (const [id, metadata] of Object.entries(loadResult.entries)) {
+      if (!finished.has(id)) pending[id] = metadata;
+    }
+    if (Object.keys(pending).length === 0) return;
+    const result = await migrateLoadedSideStore({
+      loadResult: { ok: true, entries: pending },
+      readSession,
+      writeMetadata,
+    });
+    for (const id of result.migrated) finished.add(id);
+    for (const id of result.absent) finished.add(id);
+    if (result.failed.length > 0) schedule();
+  };
+
+  void attempt();
+  return () => {
+    stopped = true;
+    if (timer) clearTimer(timer);
+    timer = null;
+  };
+};