amalgm 0.1.247 → 0.1.248

package/lib/shared-realtime-tunnel.js

@@ -936,13 +936,16 @@ function createSharedRealtimeTunnel({
         mutationId: entityIdentity.mutationId,
         version: frame.version,
         committedAt: frame.committed_at,
-      }).then(() => {
+      }).then((ack) => {
         entityMutationInflight.delete(frame.request_id);
         // An acknowledgement advances the official head. Re-read the
         // private resource immediately: the gateway compacts that head into
         // one immutable snapshot before replying, so this device never has
-        // to use its mutation tail as an `amalgm add` starting point.
-        void ensurePrivateEntityRegistry();
+        // to use its mutation tail as an `amalgm add` starting point. A
+        // legacy empty entity resource is seeded in ordered records first;
+        // intermediate heads are intentionally not imported as a usable
+        // snapshot, because they are not the complete declared home yet.
+        if (ack?.requiresSnapshot !== false) void ensurePrivateEntityRegistry();
         scheduleEntityMutationDrain();
       }).catch(() => {
         setTimeout(() => enabled && handleAck(frame), RETRY_MS).unref?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.247",
+  "version": "0.1.248",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/registration/entity-cloud.js

@@ -13,6 +13,7 @@ const crypto = require('crypto');
 
 const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@1';
 const ENTITY_CLOUD_SCHEMA_VERSION = 1;
+const BOOTSTRAP_RECONCILIATION_STATE = 'reconciling-bootstrap';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const TYPES = new Set([
   'workspace', 'folder', 'repo.git', 'file.text', 'file.binary', 'link', 'reference',
@@ -40,6 +41,15 @@ function sameRecord(left, right) {
   return stableJson(left) === stableJson(right);
 }
 
+function sameRecords(left, right) {
+  return sameRecord(snapshotFromRecords(left), snapshotFromRecords(right));
+}
+
+function recordsAreSubset(records, expected) {
+  const expectedByUuid = new Map(snapshotFromRecords(expected).records.map((record) => [record.uuid, record]));
+  return snapshotFromRecords(records).records.every((record) => sameRecord(record, expectedByUuid.get(record.uuid)));
+}
+
 function assertRecord(value) {
   if (!value || typeof value !== 'object' || typeof value.uuid !== 'string' || !UUID.test(value.uuid)
     || typeof value.type !== 'string' || !TYPES.has(value.type)
@@ -309,6 +319,26 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     `).run(current.resourceId, mutationId, stableJson(operation), createdAt, createdAt);
   }
 
+  function enqueueBootstrapReconciliation(records, current) {
+    const pending = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
+      .get(current.resourceId);
+    if (Number(pending.count) !== 0) {
+      throw new Error('entity bootstrap reconciliation already has an unfinished outbox');
+    }
+    const insert = db.prepare('INSERT INTO entity_cloud_mutations (resource_id, mutation_id, operation_json, mutation_state, created_at, updated_at) VALUES (?, ?, ?, \'pending\', ?, ?)');
+    const createdAt = now();
+    for (const record of snapshotFromRecords(records).records) {
+      queueContent(record, current.resourceId, { queue: true });
+      insert.run(
+        current.resourceId,
+        'ent_' + crypto.randomBytes(18).toString('base64url'),
+        stableJson({ kind: 'entity.upsert', record }),
+        createdAt,
+        createdAt,
+      );
+    }
+  }
+
   function assertRegistrationReady() {
     if (!ownerUserId) return;
     const current = replica();
@@ -346,7 +376,15 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     };
   }
 
-  function install({ registry, resourceId, authorityEpoch, headVersion, snapshotBase64, snapshotChecksum }) {
+  function install({
+    registry,
+    resourceId,
+    authorityEpoch,
+    headVersion,
+    snapshotBase64,
+    snapshotChecksum,
+    bootstrapRecords = null,
+  }) {
     const currentIdentity = identity();
     if (!currentIdentity.enabled || resourceId !== currentIdentity.resourceId) {
       throw new Error('cloud entity registry identity does not belong to this runtime user');
@@ -355,8 +393,86 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     const checksum = crypto.createHash('sha256').update(bytes).digest('hex');
     if (checksum !== snapshotChecksum) throw new Error('cloud entity snapshot checksum mismatch');
     const snapshot = parseSnapshot(bytes);
+    if (!Number.isInteger(Number(authorityEpoch)) || Number(authorityEpoch) < 1
+      || !Number.isInteger(Number(headVersion)) || Number(headVersion) < 0) {
+      throw new Error('entity cloud registry authority is invalid');
+    }
     const local = snapshotFromRecords(registry.syncRecords());
-    const bootstrapping = replica()?.state === 'bootstrapping';
+    const current = replica();
+    const bootstrapping = current?.state === 'bootstrapping';
+    const reconciling = current?.state === BOOTSTRAP_RECONCILIATION_STATE;
+    const trustedBootstrap = Array.isArray(bootstrapRecords)
+      ? snapshotFromRecords(bootstrapRecords).records
+      : null;
+    const emptyCloudGraph = snapshot.records.length === 0 && Number(headVersion) === 0;
+
+    // A pre-release client could create the automatic entity resource before
+    // the user-home handshake was complete, leaving a real private resource
+    // with an empty v0 graph. It is safe to repair only if the local graph is
+    // exactly the already-verified declared user home. This is not a general
+    // local-wins merge: user-selected ground remains refused until an active
+    // authoritative snapshot exists.
+    if (!current && emptyCloudGraph && trustedBootstrap && sameRecords(local.records, trustedBootstrap)) {
+      const next = {
+        resourceId,
+        deviceId: currentIdentity.deviceId,
+        authorityEpoch: Number(authorityEpoch),
+        headVersion: Number(headVersion),
+        state: BOOTSTRAP_RECONCILIATION_STATE,
+        snapshotCutoff: null,
+      };
+      db.transaction(() => {
+        saveReplica(next);
+        replaceCatalog({
+          resourceId,
+          authorityEpoch: Number(authorityEpoch),
+          headVersion: Number(headVersion),
+          records: snapshot.records,
+        });
+        enqueueBootstrapReconciliation(trustedBootstrap, next);
+      })();
+      return {
+        resourceId,
+        records: snapshot.records.length,
+        headVersion: Number(headVersion),
+        snapshotVersion: Number(headVersion),
+        reconciling: true,
+      };
+    }
+
+    if (reconciling) {
+      if (!trustedBootstrap || !sameRecords(local.records, trustedBootstrap)) {
+        throw new Error('entity bootstrap reconciliation no longer matches the verified user-home graph');
+      }
+      if (current.resourceId !== resourceId || Number(authorityEpoch) !== current.authorityEpoch
+        || Number(headVersion) < current.headVersion || !recordsAreSubset(snapshot.records, trustedBootstrap)) {
+        throw new Error('entity bootstrap reconciliation received an invalid cloud head');
+      }
+      const unsettled = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
+        .get(resourceId);
+      const complete = Number(unsettled.count) === 0 && sameRecords(snapshot.records, trustedBootstrap);
+      replaceCatalog({
+        resourceId,
+        authorityEpoch: Number(authorityEpoch),
+        headVersion: Number(headVersion),
+        records: snapshot.records,
+      });
+      saveReplica({
+        resourceId,
+        deviceId: currentIdentity.deviceId,
+        authorityEpoch: Number(authorityEpoch),
+        headVersion: Number(headVersion),
+        state: complete ? 'active' : BOOTSTRAP_RECONCILIATION_STATE,
+        snapshotCutoff: null,
+      });
+      return {
+        resourceId,
+        records: snapshot.records.length,
+        headVersion: Number(headVersion),
+        snapshotVersion: Number(headVersion),
+        reconciling: !complete,
+      };
+    }
     if (bootstrapping && !sameRecord(local, snapshot)) {
       throw new Error('first cloud entity snapshot does not match the locally bootstrapped identity graph');
     }
@@ -499,7 +615,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
 
   function claim({ limit = 16, leaseMs = 30_000 } = {}) {
     const current = replica();
-    if (!current || current.state !== 'active') return [];
+    if (!current || !['active', BOOTSTRAP_RECONCILIATION_STATE].includes(current.state)) return [];
     const boundedLimit = Math.max(1, Math.min(Number(limit) || 16, 100));
     const leaseUntil = new Date(Date.now() + Math.max(1_000, Number(leaseMs) || 30_000)).toISOString();
     const started = now();
@@ -547,7 +663,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
 
   function claimContent({ leaseMs = 30_000 } = {}) {
     const current = replica();
-    if (!current || current.state !== 'active' || !content) return null;
+    if (!current || !['active', BOOTSTRAP_RECONCILIATION_STATE].includes(current.state) || !content) return null;
     // Later registrations journal their record transactionally in SQLite.
     // Derive its content-upload cursor only after that commit exists, so a
     // failed transaction cannot publish a private object no entity names.
@@ -587,7 +703,15 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       const row = db.prepare('SELECT * FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_id = ?')
         .get(resourceId, mutationId);
       if (!row) throw new Error(`unknown entity cloud mutation ${mutationId}`);
-      if (row.mutation_state === 'synced') return { duplicate: true, version: Number(row.official_version) };
+      if (row.mutation_state === 'synced') {
+        const unsettled = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
+          .get(resourceId);
+        return {
+          duplicate: true,
+          version: Number(row.official_version),
+          requiresSnapshot: current.state !== BOOTSTRAP_RECONCILIATION_STATE || Number(unsettled.count) === 0,
+        };
+      }
       if (!['pending', 'syncing'].includes(row.mutation_state)) throw new Error(`entity cloud mutation ${mutationId} cannot sync from ${row.mutation_state}`);
       db.prepare(`
         UPDATE entity_cloud_mutations
@@ -598,7 +722,13 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       if (Number(version) > current.headVersion) {
         saveReplica({ ...current, headVersion: Number(version) });
       }
-      return { duplicate: false, version: Number(version) };
+      const unsettled = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
+        .get(resourceId);
+      return {
+        duplicate: false,
+        version: Number(version),
+        requiresSnapshot: current.state !== BOOTSTRAP_RECONCILIATION_STATE || Number(unsettled.count) === 0,
+      };
     })();
   }
 
@@ -625,7 +755,9 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
 
   function ingest({ registry, envelope, version, committedAt }) {
     const current = replica();
-    if (!current || current.state !== 'active') throw new Error('entity cloud registry is not active');
+    if (!current || !['active', BOOTSTRAP_RECONCILIATION_STATE].includes(current.state)) {
+      throw new Error('entity cloud registry is not active');
+    }
     if (envelope?.resourceId !== current.resourceId
       || envelope?.contract !== ENTITY_CLOUD_CONTRACT
       || Number(envelope?.schemaVersion) !== ENTITY_CLOUD_SCHEMA_VERSION
@@ -644,6 +776,9 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
         committedAt,
       });
     }
+    if (current.state === BOOTSTRAP_RECONCILIATION_STATE) {
+      throw new Error('entity bootstrap reconciliation cannot accept an unrelated remote mutation');
+    }
     // Remote mutations update the cloud-only catalog. They never create a
     // local watcher; `amalgm add` alone turns catalog identity into ground.
     let local;

package/runtime/scripts/amalgm-mcp/registration/service.js

@@ -259,6 +259,31 @@ function createRegistrationService({
     };
   }
 
+  /** The only local graph allowed to repair an old empty entity resource is
+   * the exact home that the user-home handshake has already verified. Any
+   * extra local entity would be user-selected ground and must wait for an
+   * active entity-cloud authority instead. */
+  async function exactUserHomeCloudRecords() {
+    const home = await bootstrapUserHome();
+    const expected = new Map();
+    for (const entry of [...home.roots, ...home.exactManaged]) {
+      expected.set(entry.record.uuid, entry.record);
+    }
+    const records = boundary.current.registry.syncRecords();
+    if (records.length !== expected.size) {
+      throw new Error('local entity graph contains ground outside the declared user home');
+    }
+    for (const record of records) {
+      const declared = expected.get(record.uuid);
+      if (!declared || ![
+        'uuid', 'type', 'parentUUID', 'name', 'status', 'version', 'payloadVersion',
+      ].every((field) => record[field] === declared[field])) {
+        throw new Error('local entity graph does not exactly match the declared user home');
+      }
+    }
+    return records;
+  }
+
   /** Materialize one already-pinned cloud tree into a fresh destination, then
    * bind its cloud UUID graph to Watch. The destination is never merged with
    * user ground: bytes are assembled in a sibling staging path and renamed
@@ -375,6 +400,7 @@ function createRegistrationService({
     },
     advanceMaterializations,
     bootstrapUserHome,
+    exactUserHomeCloudRecords,
     entityCloud,
     entityContent,
     /**

package/runtime/scripts/amalgm-mcp/registry/store.js

@@ -69,7 +69,7 @@ CREATE TABLE IF NOT EXISTS entity_cloud_replica (
   device_id TEXT NOT NULL,
   authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 1),
   head_version INTEGER NOT NULL CHECK (head_version >= 0),
-  state TEXT NOT NULL CHECK (state IN ('active', 'bootstrapping')),
+  state TEXT NOT NULL CHECK (state IN ('active', 'bootstrapping', 'reconciling-bootstrap')),
   snapshot_cutoff INTEGER,
   updated_at TEXT NOT NULL
 );
@@ -140,12 +140,17 @@ const TABLES = [...REPO_STATE_TABLES, ...CLOUD_TABLES, ...MATERIALIZATION_TABLES
 // be known locally before any observer is bound, so they cannot masquerade
 // as local registered ground. Generation 6 records the one snapshot version
 // that populated that catalog; a later mutation tail cannot pose as a fresh
-// active head for `amalgm add`. Generations 2 and 3 are
+// active head for `amalgm add`. Generation 7 adds the explicit
+// `reconciling-bootstrap` state: an old, empty entity resource may be
+// populated only from the already-verified exact user-home graph, and cannot
+// admit ordinary registration or materialization until its ordered outbox
+// becomes an active cloud snapshot. Generations 2 and 3 are
 // additive predecessors: migrations only add tables beside existing identity
 // records, never rewrite UUIDs or evidence bindings. The per-tree era never
 // stamped a version and reads 0 — an older generation, refused distinctly
 // from loss until an explicit migration exists.
-const GENERATION = 6;
+const GENERATION = 7;
+const BOOTSTRAP_RECONCILIATION_GENERATION = 6;
 const MATERIALIZATION_GENERATION = 5;
 const CLOUD_GENERATION = 4;
 const REPO_STATE_GENERATION = 3;
@@ -173,6 +178,9 @@ function inspect(db) {
 
 function isMigratableGenerationShape(db, inspection) {
   const generation = db.pragma('user_version', { simple: true });
+  if (generation === BOOTSTRAP_RECONCILIATION_GENERATION) {
+    return inspection.missing.length === 0;
+  }
   if (generation === MATERIALIZATION_GENERATION) {
     return inspection.missing.length === 1
       && inspection.missing[0] === 'entity_cloud_catalog_state'
@@ -196,12 +204,45 @@ function isMigratableGenerationShape(db, inspection) {
     && REPO_STATE_TABLES.every((name) => !inspection.missing.includes(name));
 }
 
+/** SQLite cannot widen a CHECK constraint in place. This is a schema
+ * migration—not a state rewrite: every old row is copied byte-for-byte into
+ * the wider replica table in one transaction. */
+function migrateBootstrapReconciliationState(db) {
+  db.transaction(() => {
+    db.exec(`
+      ALTER TABLE entity_cloud_replica RENAME TO entity_cloud_replica_v6;
+      CREATE TABLE entity_cloud_replica (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        resource_id TEXT NOT NULL,
+        device_id TEXT NOT NULL,
+        authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 1),
+        head_version INTEGER NOT NULL CHECK (head_version >= 0),
+        state TEXT NOT NULL CHECK (state IN ('active', 'bootstrapping', 'reconciling-bootstrap')),
+        snapshot_cutoff INTEGER,
+        updated_at TEXT NOT NULL
+      );
+      INSERT INTO entity_cloud_replica (
+        singleton, resource_id, device_id, authority_epoch, head_version,
+        state, snapshot_cutoff, updated_at
+      )
+      SELECT
+        singleton, resource_id, device_id, authority_epoch, head_version,
+        state, snapshot_cutoff, updated_at
+      FROM entity_cloud_replica_v6;
+      DROP TABLE entity_cloud_replica_v6;
+    `);
+  })();
+}
+
 function createStore(db) {
   const generation = db.pragma('user_version', { simple: true });
   const inspection = inspect(db);
   if (!inspection.fresh && generation !== GENERATION && !isMigratableGenerationShape(db, inspection)) {
     throw new Error(`identity registry is schema generation ${generation}, this code speaks ${GENERATION} — migration is an explicit act, never a silent table creation`);
   }
+  if (generation === BOOTSTRAP_RECONCILIATION_GENERATION) {
+    migrateBootstrapReconciliationState(db);
+  }
   db.exec(SCHEMA);
   db.pragma(`user_version = ${GENERATION}`);
 

package/runtime/scripts/amalgm-mcp/server/routes/entities.js

@@ -146,6 +146,20 @@ async function handleEntityRoutes(ctx) {
     const body = await ctx.readJsonBody();
     const service = registrationService();
     try {
+      const existing = service.entityCloud.replica();
+      let bootstrapRecords = null;
+      try {
+        const snapshot = JSON.parse(Buffer.from(String(body?.snapshotBase64 || ''), 'base64').toString('utf8'));
+        if (
+          existing?.state === 'reconciling-bootstrap'
+          || (Number(body?.headVersion) === 0 && Array.isArray(snapshot?.records) && snapshot.records.length === 0)
+        ) {
+          bootstrapRecords = await service.exactUserHomeCloudRecords();
+        }
+      } catch {
+        // install performs the authoritative checksum and shape validation;
+        // this lookahead only decides whether exact bootstrap proof is needed.
+      }
       ctx.sendJson(200, service.entityCloud.install({
         registry: service.registration.registry,
         resourceId: body?.resourceId,
@@ -153,6 +167,7 @@ async function handleEntityRoutes(ctx) {
         headVersion: body?.headVersion,
         snapshotBase64: body?.snapshotBase64,
         snapshotChecksum: body?.snapshotChecksum,
+        bootstrapRecords,
       }));
     } catch (error) {
       ctx.sendJson(409, { error: error.message });

package/runtime/scripts/amalgm-mcp/tests/entity-cloud.test.js

@@ -76,6 +76,69 @@ test('a signed-in registration is refused until the cloud entity resource is act
   assert.doesNotThrow(() => cloud.assertRegistrationReady());
 });
 
+test('only an exact verified bootstrap graph can repair a legacy empty entity resource', () => {
+  const db = new Database(':memory:');
+  const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1' });
+  const registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
+  const root = registry.enrollRoot({ type: 'workspace', name: 'agents' });
+  const resourceId = cloud.identity().resourceId;
+  const empty = Buffer.from(JSON.stringify(snapshotFromRecords([])), 'utf8');
+
+  const first = cloud.install({
+    registry,
+    resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: empty.toString('base64'),
+    snapshotChecksum: require('crypto').createHash('sha256').update(empty).digest('hex'),
+    bootstrapRecords: registry.syncRecords(),
+  });
+  assert.equal(first.reconciling, true);
+  assert.equal(cloud.replica().state, 'reconciling-bootstrap');
+  assert.throws(() => cloud.assertRegistrationReady(), /not ready/,
+    'ordinary register stays closed until the ordered repair reaches a full cloud head');
+
+  const claimed = cloud.claim();
+  assert.equal(claimed.length, 1);
+  assert.equal(claimed[0].baseVersion, 0);
+  assert.equal(cloud.acknowledge({
+    resourceId,
+    mutationId: claimed[0].mutationId,
+    version: 1,
+    committedAt: '2026-08-05T00:00:00.000Z',
+  }).requiresSnapshot, true, 'only the final ordered acknowledgement asks for a usable snapshot');
+
+  const completed = snapshotFromRecords(registry.syncRecords());
+  const final = cloud.install({
+    registry,
+    resourceId,
+    authorityEpoch: 1,
+    headVersion: 1,
+    snapshotBase64: Buffer.from(JSON.stringify(completed), 'utf8').toString('base64'),
+    snapshotChecksum: require('crypto').createHash('sha256').update(JSON.stringify(completed)).digest('hex'),
+    bootstrapRecords: registry.syncRecords(),
+  });
+  assert.equal(final.reconciling, false);
+  assert.equal(cloud.replica().state, 'active');
+  assert.doesNotThrow(() => cloud.assertRegistrationReady());
+
+  const unsafeDb = new Database(':memory:');
+  const unsafeCloud = createEntityCloud({ db: unsafeDb, userId: 'user-1', deviceId: 'unsafe-device' });
+  const unsafeRegistry = createRegistry({ db: unsafeDb, ephemeral: true, emit: () => {}, journal: unsafeCloud.journal });
+  const safeRoot = unsafeRegistry.enrollRoot({ type: 'workspace', name: 'agents' });
+  unsafeRegistry.create({ type: 'file.text', parentUUID: safeRoot.uuid, name: 'not-a-default.md', payloadVersion: 'a'.repeat(64) });
+  assert.throws(() => unsafeCloud.install({
+    registry: unsafeRegistry,
+    resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: empty.toString('base64'),
+    snapshotChecksum: require('crypto').createHash('sha256').update(empty).digest('hex'),
+    bootstrapRecords: unsafeRegistry.syncRecords().filter((record) => record.uuid === safeRoot.uuid),
+  }), /conflicts with locally bound ground/,
+    'an empty cloud resource never authorizes arbitrary local ground');
+});
+
 test('a compacted remote snapshot enters the cloud catalog, not locally watched identity, and add claims its immutable content', () => {
   const sourceDb = new Database(':memory:');
   const sourceCloud = createEntityCloud({ db: sourceDb, userId: 'user-1', deviceId: 'source-device' });

package/runtime/scripts/amalgm-mcp/tests/entity.registry.test.js

@@ -97,7 +97,7 @@ test('the additive entity-cloud migration preserves a generation-2 registry', ()
 
   const registry = createRegistry({ db, ephemeral: true, emit: () => {} });
   assert.equal(registry.epoch(), 'legacy-epoch', 'the existing identity epoch survives');
-  assert.equal(db.pragma('user_version', { simple: true }), 6);
+  assert.equal(db.pragma('user_version', { simple: true }), 7);
   assert.ok(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'repo_states'").get(),
     'the repo-state document table is added without replacing identity');
   assert.ok(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'entity_cloud_mutations'").get(),
@@ -114,11 +114,45 @@ test('the active-snapshot marker migrates beside an existing materialization cat
 
   const reopened = createRegistry({ db, ephemeral: true, emit: () => {} });
   assert.ok(reopened.epoch(), 'the previous identity database remains usable');
-  assert.equal(db.pragma('user_version', { simple: true }), 6);
+  assert.equal(db.pragma('user_version', { simple: true }), 7);
   assert.ok(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'entity_cloud_catalog_state'").get(),
     'the separate pinned-snapshot marker is created without rewriting identities');
 });
 
+test('the bootstrap-reconciliation migration preserves a generation-6 cloud replica', () => {
+  const db = new Database(':memory:');
+  createRegistry({ db, ephemeral: true, emit: () => {} });
+  db.exec([
+    'ALTER TABLE entity_cloud_replica RENAME TO entity_cloud_replica_v7;',
+    'CREATE TABLE entity_cloud_replica (',
+    '  singleton INTEGER PRIMARY KEY CHECK (singleton = 1),',
+    '  resource_id TEXT NOT NULL,',
+    '  device_id TEXT NOT NULL,',
+    '  authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 1),',
+    '  head_version INTEGER NOT NULL CHECK (head_version >= 0),',
+    "  state TEXT NOT NULL CHECK (state IN ('active', 'bootstrapping')),",
+    '  snapshot_cutoff INTEGER,',
+    '  updated_at TEXT NOT NULL',
+    ');',
+    'INSERT INTO entity_cloud_replica SELECT * FROM entity_cloud_replica_v7;',
+    'DROP TABLE entity_cloud_replica_v7;',
+  ].join('\n'));
+  db.prepare([
+    'INSERT INTO entity_cloud_replica (',
+    '  singleton, resource_id, device_id, authority_epoch, head_version,',
+    '  state, snapshot_cutoff, updated_at',
+    ") VALUES (1, 'pvr_legacy', 'device', 1, 4, 'active', NULL, 'now')",
+  ].join('\n')).run();
+  db.pragma('user_version = 6');
+
+  createRegistry({ db, ephemeral: true, emit: () => {} });
+  assert.equal(db.pragma('user_version', { simple: true }), 7);
+  assert.equal(db.prepare('SELECT state FROM entity_cloud_replica WHERE singleton = 1').get().state, 'active');
+  assert.doesNotThrow(() => db.prepare(
+    "UPDATE entity_cloud_replica SET state = 'reconciling-bootstrap' WHERE singleton = 1",
+  ).run(), 'the widened state is durable after migration');
+});
+
 test('an entity commit and its cloud delivery intent are one SQLite transaction', () => {
   const db = new Database(':memory:');
   let nextMutation = 0;