fix(runtime-host,storage): migrate untouched legacy opencode-free seeds atomically

Existing installs never re-ran bootstrap seeding, so upgrades kept
retired ids and never received newly derived free models.

Built-in seed evolution is one connection-catalog-authority CAS
mutation (migrateSystemSeed): a row whose enabledModelIds still exactly
match a historical system seed follows the current seed, its static
inventory is re-derived from the current build, and a default target
the migration removes is retargeted inside the same document write — so
no restart can observe enabled ids without their inventory, or a nulled
default awaiting a second write. Any other inventory (including a
reordering) is a user selection and is never touched; an already-null
default stays null. Idempotent by construction.

The exact-match enumeration is deliberately lossy and every seed change
must append the prior value; the versioned seed policy discussed in
 #3354 is the durable replacement. Tests start from an actual
pre-#3409 persisted document and verify both completion and the restart
no-op on the far side of the single commit boundary.

Refs #3409

Generated-by: Claude Code

Author: cunninghamcard-bit

packages/core/src/runtime-policy.ts

@@ -276,6 +276,21 @@ export interface RemoveCatalogConnectionInput {
   readonly expected: ConnectionVersionBasis;
 }
 
+/**
+ * Built-in seed evolution as one atomic catalog mutation: a row still exactly
+ * matching a historical system seed follows the current seed — enabled ids AND
+ * the static inventory — and a system default the migration removes is
+ * retargeted in the same document write. Any other inventory is a user
+ * selection and is never touched; an already-null default stays null.
+ */
+export interface MigrateSystemSeedInput {
+  readonly slug: string;
+  readonly providerType: ProviderType;
+  readonly legacyEnabledModelIds: readonly (readonly string[])[];
+  readonly enabledModelIds: readonly string[];
+  readonly defaultModelId: string;
+}
+
 export interface SetDefaultConnectionTargetInput {
   readonly expectedCatalogRevision: Revision;
   readonly target: ConnectionTarget | null;

packages/runtime-host/src/__tests__/bootstrap-runtime-policy.test.ts

@@ -163,71 +163,96 @@ test('an invalid optional environment credential does not keep bootstrap active'
   });
 });
 
-test('an untouched legacy opencode-free seed follows the current seed', async () => {
+test('a historical persisted seed migrates atomically, inventory and default included', async () => {
   await withFixture(async ({ root, stores }) => {
-    const created = await stores.connectionCatalog.create({
-      expectedCatalogRevision: 0,
-      connection: {
-        slug: 'opencode-free',
-        name: 'OpenCode Free',
-        providerType: 'opencode-free',
-        enabled: true,
-        enabledModelIds: ['nemotron-3-ultra-free', 'mimo-v2.5-free', 'deepseek-v4-flash-free'],
-      },
-    });
-    assert.equal(created.kind, 'committed');
+    // An actual pre-#3409 persisted document: the three-model seed, the
+    // pinned four-model fallback inventory of that build, and a default
+    // target on a model the migration removes.
+    const connectionId = '00000000-0000-4000-8000-000000000001';
+    await writeFile(
+      join(root, 'connection-catalog.json'),
+      `${JSON.stringify({
+        schemaVersion: 1,
+        revision: 7,
+        defaultTarget: { connectionId, modelId: 'deepseek-v4-flash-free' },
+        connections: [
+          {
+            connectionId,
+            revision: 3,
+            slug: 'opencode-free',
+            name: 'OpenCode Free',
+            providerType: 'opencode-free',
+            enabled: true,
+            enabledModelIds: ['nemotron-3-ultra-free', 'mimo-v2.5-free', 'deepseek-v4-flash-free'],
+            models: [
+              { id: 'nemotron-3-ultra-free' },
+              { id: 'mimo-v2.5-free' },
+              { id: 'big-pickle' },
+              { id: 'deepseek-v4-flash-free' },
+            ],
+            modelSource: 'fallback',
+            modelsFetchedAt: 0,
+          },
+        ],
+      })}\n`,
+    );
 
     await ensureBootstrapRuntimePolicy({ workspaceRoot: root, stores, environment: {} });
 
+    // One document write carried all three: enabled ids, the re-derived
+    // static inventory, and the retargeted default.
     const catalog = await stores.connectionCatalog.getSnapshot();
-    const free = catalog.connections.find(({ slug }) => slug === 'opencode-free');
-    assert.deepEqual(free?.enabledModelIds, [...OPENCODE_FREE_DEFAULT_ENABLED_MODELS]);
+    const migrated = catalog.connections.find(({ slug }) => slug === 'opencode-free');
+    assert.deepEqual(migrated?.enabledModelIds, [...OPENCODE_FREE_DEFAULT_ENABLED_MODELS]);
+    assert.deepEqual(
+      migrated?.models.map(({ id }) => id),
+      [...OPENCODE_FREE_DEFAULT_ENABLED_MODELS],
+    );
+    assert.deepEqual(catalog.defaultTarget, {
+      connectionId,
+      modelId: OPENCODE_FREE_DEFAULT_MODEL,
+    });
 
-    // Idempotent: a second bootstrap leaves the migrated row unchanged.
+    // Restart on the far side of the commit boundary: a second bootstrap is a
+    // byte-identical no-op. (On the near side the single write never happened,
+    // so the original document simply migrates on the next start.)
     await ensureBootstrapRuntimePolicy({ workspaceRoot: root, stores, environment: {} });
     assert.deepEqual(await stores.connectionCatalog.getSnapshot(), catalog);
   });
 });
 
-test('a legacy seed migrates and repairs a default target the migration nulled', async () => {
+test('a historical seed with a user-cleared default migrates without inventing one', async () => {
   await withFixture(async ({ root, stores }) => {
-    const created = await stores.connectionCatalog.create({
-      expectedCatalogRevision: 0,
-      connection: {
-        slug: 'opencode-free',
-        name: 'OpenCode Free',
-        providerType: 'opencode-free',
-        enabled: true,
-        enabledModelIds: ['nemotron-3-ultra-free', 'mimo-v2.5-free', 'deepseek-v4-flash-free'],
-      },
-    });
-    assert.equal(created.kind, 'committed');
-    if (created.kind !== 'committed') return;
-    const free = created.snapshot.connections[0]!;
-    // Default target on a model the migration removes: the retained-target
-    // rules null it, and bootstrap must re-seed it.
-    const targeted = await stores.connectionCatalog.setDefaultTarget({
-      expectedCatalogRevision: created.snapshot.revision,
-      target: { connectionId: free.connectionId, modelId: 'deepseek-v4-flash-free' },
-    });
-    assert.equal(targeted.kind, 'committed');
+    const connectionId = '00000000-0000-4000-8000-000000000002';
+    await writeFile(
+      join(root, 'connection-catalog.json'),
+      `${JSON.stringify({
+        schemaVersion: 1,
+        revision: 4,
+        defaultTarget: null,
+        connections: [
+          {
+            connectionId,
+            revision: 2,
+            slug: 'opencode-free',
+            name: 'OpenCode Free',
+            providerType: 'opencode-free',
+            enabled: true,
+            enabledModelIds: ['nemotron-3-ultra-free'],
+            models: [{ id: 'nemotron-3-ultra-free' }],
+            modelSource: 'fallback',
+            modelsFetchedAt: 0,
+          },
+        ],
+      })}\n`,
+    );
 
     await ensureBootstrapRuntimePolicy({ workspaceRoot: root, stores, environment: {} });
 
     const catalog = await stores.connectionCatalog.getSnapshot();
     const migrated = catalog.connections.find(({ slug }) => slug === 'opencode-free');
     assert.deepEqual(migrated?.enabledModelIds, [...OPENCODE_FREE_DEFAULT_ENABLED_MODELS]);
-    // The migration write also refreshes the stored inventory to the current
-    // build's candidates exactly, so every model the picker offers is one
-    // execution admission accepts and no stale id survives.
-    assert.deepEqual(
-      migrated?.models.map(({ id }) => id),
-      [...OPENCODE_FREE_DEFAULT_ENABLED_MODELS],
-    );
-    assert.deepEqual(catalog.defaultTarget, {
-      connectionId: free.connectionId,
-      modelId: OPENCODE_FREE_DEFAULT_MODEL,
-    });
+    assert.equal(catalog.defaultTarget, null);
   });
 });
 

packages/runtime-host/src/server/bootstrap-runtime-policy.ts

@@ -41,6 +41,22 @@ export async function ensureBootstrapRuntimePolicy(input: {
   const journalPath = join(input.workspaceRoot, JOURNAL_FILE);
   const resuming = await readJournal(journalPath);
   const initialCatalog = await input.stores.connectionCatalog.getSnapshot();
+  if (initialCatalog.connections.length > 0) {
+    // One atomic catalog mutation: enabled ids, static inventory, and a
+    // retarget of a system default the migration removes all land in the same
+    // document write, so no restart can observe a half-migrated row.
+    try {
+      await input.stores.connectionCatalog.migrateSystemSeed({
+        slug: 'opencode-free',
+        providerType: 'opencode-free',
+        legacyEnabledModelIds: LEGACY_OPENCODE_FREE_SEEDS,
+        enabledModelIds: OPENCODE_FREE_DEFAULT_ENABLED_MODELS,
+        defaultModelId: OPENCODE_FREE_DEFAULT_MODEL,
+      });
+    } catch (error) {
+      input.onDeferredError?.(error);
+    }
+  }
   if (!resuming) {
     if (initialCatalog.connections.length > 0) return;
     await writeJournal(journalPath);
@@ -146,6 +162,21 @@ async function ensureConnection(
   throw new Error(`Bootstrap Connection could not be created: ${seed.slug}`);
 }
 
+/**
+ * Every opencode-free inventory a past release seeded, verbatim. A row still
+ * equal to one of these is provably system-owned and may follow the current
+ * seed; any other value is a user selection and is never touched. Every
+ * release that changes the derived seed must append the previous value here,
+ * or rows it planted read as user selections forever. (This exact-match
+ * enumeration is deliberately lossy; the versioned seed policy discussed in
+ * #3354 is the durable replacement.)
+ */
+const LEGACY_OPENCODE_FREE_SEEDS: readonly (readonly string[])[] = [
+  ['big-pickle'],
+  ['nemotron-3-ultra-free'],
+  ['nemotron-3-ultra-free', 'mimo-v2.5-free', 'deepseek-v4-flash-free'],
+];
+
 async function removeFailedBootstrapConnection(
   stores: RuntimePolicyStoresWriter,
   connection: ConnectionCatalogEntry,

packages/storage/src/runtime-policy-stores.ts

@@ -11,6 +11,7 @@ import type {
   RemoveCatalogConnectionInput,
   RuntimePolicySnapshot,
   SetCredentialInput,
+  MigrateSystemSeedInput,
   SetDefaultConnectionTargetInput,
   UpdateCatalogConnectionInput,
 } from '@maka/core/runtime-policy';
@@ -87,6 +88,7 @@ export interface ConnectionCatalogWriter extends ConnectionCatalogReader {
   setDefaultTarget(
     input: SetDefaultConnectionTargetInput,
   ): Promise<ConnectionCatalogMutationResult>;
+  migrateSystemSeed(input: MigrateSystemSeedInput): Promise<ConnectionCatalogMutationResult>;
 }
 
 export interface CredentialVaultReader {
@@ -200,6 +202,7 @@ function createWriterFacade(coordinator: RuntimePolicyCoordinator): RuntimePolic
       update: (input) => coordinator.updateConnection(input),
       remove: (input) => coordinator.removeConnection(input),
       setDefaultTarget: (input) => coordinator.setDefaultTarget(input),
+      migrateSystemSeed: (input) => coordinator.migrateSystemSeed(input),
     },
     credentialVault: {
       getSnapshot: () => coordinator.getVaultSnapshot(),

packages/storage/src/runtime-policy/connection-catalog-document.ts

@@ -25,6 +25,7 @@ import {
   type CreateCatalogConnectionInput,
   type RemoveCatalogConnectionInput,
   type SetDefaultConnectionTargetInput,
+  type MigrateSystemSeedInput,
   type UpdateCatalogConnectionInput,
 } from '@maka/core/runtime-policy';
 import {
@@ -310,6 +311,66 @@ export class ConnectionCatalogDocumentOwner {
     return committed(next);
   }
 
+  /**
+   * Built-in seed evolution as ONE atomic catalog mutation. A row whose
+   * `enabledModelIds` still exactly match a historical system seed is provably
+   * system-owned: it follows the current seed, its static inventory is
+   * re-derived from the current build, and a default target the migration
+   * removes is retargeted inside the same document write — so no restart can
+   * observe enabled ids without their inventory, or a nulled default awaiting
+   * a second write. Any other inventory (including a reordering) is a user
+   * selection and is never touched; an already-null default stays null.
+   */
+  async migrateSystemSeed(
+    root: string,
+    input: MigrateSystemSeedInput,
+  ): Promise<ConnectionCatalogMutationResult> {
+    if (!input.enabledModelIds.includes(input.defaultModelId)) {
+      throw codecError('invalid_connection_input', 'Seed default must be in the seed selection');
+    }
+    const current = await this.read(root);
+    const index = current.connections.findIndex(
+      (item) => item.slug === input.slug && item.providerType === input.providerType,
+    );
+    const previous = current.connections[index];
+    const sameIds = (left: readonly string[], right: readonly string[]) =>
+      left.length === right.length && left.every((id, position) => id === right[position]);
+    if (
+      !previous ||
+      sameIds(previous.enabledModelIds, input.enabledModelIds) ||
+      !input.legacyEnabledModelIds.some((seed) => sameIds(previous.enabledModelIds, seed))
+    ) {
+      return committed(current);
+    }
+    const fallbackModels = fallbackInventory(previous.providerType);
+    const {
+      lastTest: _lastTest,
+      modelSource: _modelSource,
+      modelsFetchedAt: _modelsFetchedAt,
+      ...retained
+    } = previous;
+    const connections = [...current.connections];
+    connections[index] = {
+      ...retained,
+      revision: nextRevision(previous.revision),
+      enabledModelIds: [...input.enabledModelIds],
+      models: fallbackModels,
+      ...(fallbackModels.length > 0
+        ? { modelSource: 'fallback' as const, modelsFetchedAt: 0 }
+        : {}),
+    };
+    const target = current.defaultTarget;
+    const defaultTarget =
+      target !== null &&
+      target.connectionId === previous.connectionId &&
+      !input.enabledModelIds.includes(target.modelId)
+        ? { connectionId: previous.connectionId, modelId: input.defaultModelId }
+        : target;
+    const next = this.nextDocument(current, connections, defaultTarget);
+    await this.write(root, next);
+    return committed(next);
+  }
+
   async setDefaultTarget(
     root: string,
     rawInput: SetDefaultConnectionTargetInput,

packages/storage/src/runtime-policy/coordinator.ts

@@ -29,6 +29,7 @@ import {
   type RequestHeaderUpdate,
   type SavedRequestHeaders,
   type SetCredentialInput,
+  type MigrateSystemSeedInput,
   type SetDefaultConnectionTargetInput,
   type UpdateCatalogConnectionInput,
 } from '@maka/core/runtime-policy';
@@ -296,6 +297,10 @@ export class RuntimePolicyCoordinator {
     return this.inLane((root) => this.catalog.setDefaultTarget(root, input));
   }
 
+  migrateSystemSeed(input: MigrateSystemSeedInput) {
+    return this.inLane((root) => this.catalog.migrateSystemSeed(root, input));
+  }
+
   setCredential(rawInput: SetCredentialInput) {
     return this.setCredentialWithAuthority(rawInput, 'client');
   }