amalgm 0.1.155 → 0.1.156

package/runtime/scripts/amalgm-mcp/state/attachments.js

@@ -0,0 +1,187 @@
+'use strict';
+
+const { cachedStatement, openLocalDb } = require('./db');
+const { appendStateEvent } = require('./events');
+
+const SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
+const ATTACHMENT_ID = /^[A-Za-z0-9_-]{16,160}$/;
+
+function invalid(message, statusCode = 400) {
+  return Object.assign(new Error(message), { statusCode });
+}
+
+function requiredText(value, name, max = 4096) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text || text.length > max || /[\u0000-\u001f\u007f]/.test(text)) {
+    throw invalid(`${name} must be a non-empty string of at most ${max} characters`);
+  }
+  return text;
+}
+
+function normalizeRow(row) {
+  if (!row) return null;
+  return {
+    attachmentId: row.attachment_id,
+    resourceId: row.resource_id,
+    localPath: row.local_path,
+    state: row.attachment_state,
+    attemptCount: Number(row.attempt_count),
+    nextAttemptAt: row.next_attempt_at || null,
+    lastError: row.last_error || null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function enqueueAttachment(input, options = {}) {
+  const attachmentId = requiredText(input?.attachmentId, 'attachmentId', 160);
+  const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
+  const localPath = requiredText(input?.localPath, 'localPath');
+  if (!ATTACHMENT_ID.test(attachmentId)) throw invalid('attachmentId has an invalid format');
+  if (!SHARED_RESOURCE_ID.test(resourceId)) throw invalid('resourceId has an invalid format');
+  const database = options.database || openLocalDb();
+  const existing = cachedStatement(
+    database,
+    'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?',
+  ).get(attachmentId);
+  if (existing) {
+    const attachment = normalizeRow(existing);
+    if (attachment.resourceId !== resourceId || attachment.localPath !== localPath) {
+      throw invalid(`attachmentId ${attachmentId} was reused with different content`, 409);
+    }
+    return { attachment, duplicate: true };
+  }
+  const now = new Date().toISOString();
+  try {
+    cachedStatement(database, `
+      INSERT INTO shared_resource_attachments (
+        attachment_id, resource_id, local_path, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?)
+    `).run(attachmentId, resourceId, localPath, now, now);
+  } catch (error) {
+    if (String(error?.code || '').includes('CONSTRAINT')) {
+      throw invalid('that resource or local path already has an attachment request', 409);
+    }
+    throw error;
+  }
+  const attachment = normalizeRow(
+    cachedStatement(database, 'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?')
+      .get(attachmentId),
+  );
+  appendStateEvent({
+    resource: 'shared:attachments',
+    op: 'update',
+    id: attachmentId,
+    sharedResourceId: resourceId,
+    value: { state: 'pending' },
+    source: 'shared:attachment',
+  });
+  return { attachment, duplicate: false };
+}
+
+function claimAttachments(options = {}) {
+  const database = options.database || openLocalDb();
+  const limit = Math.max(1, Math.min(Number(options.limit) || 4, 20));
+  const leaseMs = Math.max(1000, Number(options.leaseMs) || 30_000);
+  const now = new Date().toISOString();
+  const leaseUntil = new Date(Date.now() + leaseMs).toISOString();
+  return database.transaction(() => {
+    const rows = cachedStatement(database, `
+      SELECT * FROM shared_resource_attachments
+      WHERE attachment_state = 'pending'
+         OR (attachment_state = 'syncing' AND (next_attempt_at IS NULL OR next_attempt_at <= ?))
+      ORDER BY created_at ASC
+      LIMIT ?
+    `).all(now, limit);
+    const claim = cachedStatement(database, `
+      UPDATE shared_resource_attachments
+      SET attachment_state = 'syncing',
+          attempt_count = attempt_count + 1,
+          next_attempt_at = ?,
+          updated_at = ?
+      WHERE attachment_id = ?
+    `);
+    return rows.map((row) => {
+      claim.run(leaseUntil, now, row.attachment_id);
+      return normalizeRow(
+        cachedStatement(database, 'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?')
+          .get(row.attachment_id),
+      );
+    });
+  })();
+}
+
+function acknowledgeAttachment(attachmentIdInput, payload, options = {}) {
+  const attachmentId = requiredText(attachmentIdInput, 'attachmentId', 160);
+  const database = options.database || openLocalDb();
+  const row = cachedStatement(
+    database,
+    'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?',
+  ).get(attachmentId);
+  if (!row) throw invalid(`unknown attachment ${attachmentId}`, 404);
+  const attachment = normalizeRow(row);
+  if (attachment.state === 'attached') return { attachment, duplicate: true };
+  if (payload?.resourceId !== attachment.resourceId) {
+    throw invalid('attachment response resource mismatch', 409);
+  }
+
+  const installed = require('./docs').installCloudDocSnapshot(attachment.localPath, payload);
+  const now = new Date().toISOString();
+  cachedStatement(database, `
+    UPDATE shared_resource_attachments
+    SET attachment_state = 'attached',
+        next_attempt_at = NULL,
+        last_error = NULL,
+        updated_at = ?
+    WHERE attachment_id = ?
+  `).run(now, attachmentId);
+  return {
+    attachment: normalizeRow(
+      cachedStatement(database, 'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?')
+        .get(attachmentId),
+    ),
+    replica: installed.replica,
+    duplicate: false,
+  };
+}
+
+function failAttachment(attachmentIdInput, failure, options = {}) {
+  const attachmentId = requiredText(attachmentIdInput, 'attachmentId', 160);
+  const retryable = failure?.retryable !== false;
+  const database = options.database || openLocalDb();
+  const result = cachedStatement(database, `
+    UPDATE shared_resource_attachments
+    SET attachment_state = ?,
+        next_attempt_at = ?,
+        last_error = ?,
+        updated_at = ?
+    WHERE attachment_id = ? AND attachment_state != 'attached'
+  `).run(
+    retryable ? 'syncing' : 'rejected',
+    retryable ? new Date(Date.now() + 1000).toISOString() : null,
+    String(failure?.message || 'attachment failed').slice(0, 4000),
+    new Date().toISOString(),
+    attachmentId,
+  );
+  if (!result.changes) throw invalid(`unknown or completed attachment ${attachmentId}`, 404);
+  return normalizeRow(
+    cachedStatement(database, 'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?')
+      .get(attachmentId),
+  );
+}
+
+function getAttachment(attachmentId, options = {}) {
+  const database = options.database || openLocalDb();
+  return normalizeRow(
+    cachedStatement(database, 'SELECT * FROM shared_resource_attachments WHERE attachment_id = ?')
+      .get(attachmentId),
+  );
+}
+
+module.exports = {
+  acknowledgeAttachment,
+  claimAttachments,
+  enqueueAttachment,
+  failAttachment,
+  getAttachment,
+};

package/runtime/scripts/amalgm-mcp/state/db.js

@@ -68,6 +68,8 @@ function migrate(database = openLocalDb()) {
       value_json TEXT,
       patch_json TEXT,
       client_mutation_id TEXT,
+      mutation_id TEXT,
+      shared_resource_id TEXT,
       source TEXT,
       resource_version INTEGER
     );
@@ -77,6 +79,136 @@ function migrate(database = openLocalDb()) {
     -- from earlier releases.
     DROP INDEX IF EXISTS event_log_resource_seq_idx;
 
+    -- Durable edit identity and cloud delivery state live here. event_log
+    -- remains the short published/replay projection: a mutation enters it
+    -- only after the materialized local store is current.
+    CREATE TABLE IF NOT EXISTS mutation_journal (
+      journal_id INTEGER PRIMARY KEY AUTOINCREMENT,
+      channel_id TEXT NOT NULL,
+      local_resource TEXT NOT NULL,
+      shared_resource_id TEXT,
+      mutation_id TEXT NOT NULL,
+      device_id TEXT,
+      authority_epoch INTEGER NOT NULL DEFAULT 0 CHECK (authority_epoch >= 0),
+      base_cloud_version INTEGER NOT NULL DEFAULT 0 CHECK (base_cloud_version >= 0),
+      official_cloud_version INTEGER CHECK (official_cloud_version IS NULL OR official_cloud_version >= 0),
+      contract TEXT NOT NULL,
+      schema_version INTEGER NOT NULL CHECK (schema_version > 0),
+      operation_kind TEXT NOT NULL,
+      operation_json TEXT NOT NULL,
+      mutation_origin TEXT NOT NULL DEFAULT 'local'
+        CHECK (mutation_origin IN ('local', 'cloud')),
+      mutation_state TEXT NOT NULL DEFAULT 'saving-local'
+        CHECK (mutation_state IN (
+          'saving-local',
+          'saved-local',
+          'syncing',
+          'synced',
+          'rejected',
+          'conflicted'
+        )),
+      local_revision INTEGER,
+      materialized_at TEXT,
+      event_seq INTEGER,
+      attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+      next_attempt_at TEXT,
+      last_error TEXT,
+      cloud_committed_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      UNIQUE (channel_id, mutation_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS mutation_journal_cloud_outbox_idx
+      ON mutation_journal (mutation_state, next_attempt_at, journal_id)
+      WHERE shared_resource_id IS NOT NULL AND mutation_origin = 'local';
+
+    CREATE INDEX IF NOT EXISTS mutation_journal_shared_version_idx
+      ON mutation_journal (shared_resource_id, official_cloud_version)
+      WHERE shared_resource_id IS NOT NULL;
+
+    CREATE UNIQUE INDEX IF NOT EXISTS mutation_journal_official_version_unique_idx
+      ON mutation_journal (shared_resource_id, official_cloud_version)
+      WHERE shared_resource_id IS NOT NULL AND official_cloud_version IS NOT NULL;
+
+    CREATE INDEX IF NOT EXISTS mutation_journal_event_seq_idx
+      ON mutation_journal (event_seq)
+      WHERE event_seq IS NOT NULL;
+
+    -- Runtime-owned binding between one cloud-authoritative resource and its
+    -- real local materialization. Browsers cannot turn a local file into a
+    -- cloud source by adding a request flag; promotion/join installs this
+    -- binding, and every edit thereafter discovers authority here.
+    CREATE TABLE IF NOT EXISTS shared_resource_replicas (
+      resource_id TEXT PRIMARY KEY,
+      local_resource TEXT NOT NULL UNIQUE,
+      local_path TEXT NOT NULL UNIQUE,
+      contract TEXT NOT NULL,
+      schema_version INTEGER NOT NULL CHECK (schema_version > 0),
+      authority_epoch INTEGER NOT NULL CHECK (authority_epoch > 0),
+      applied_version INTEGER NOT NULL DEFAULT 0 CHECK (applied_version >= 0),
+      snapshot_version INTEGER NOT NULL DEFAULT 0 CHECK (snapshot_version >= 0),
+      snapshot_checksum TEXT,
+      sync_status TEXT NOT NULL DEFAULT 'synced'
+        CHECK (sync_status IN (
+          'saving-local',
+          'saved-local',
+          'syncing',
+          'synced',
+          'rejected',
+          'conflicted'
+        )),
+      last_error TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      CHECK (snapshot_version <= applied_version)
+    );
+
+    CREATE INDEX IF NOT EXISTS shared_resource_replicas_path_idx
+      ON shared_resource_replicas (local_path);
+
+    CREATE TABLE IF NOT EXISTS shared_resource_promotions (
+      promotion_id TEXT PRIMARY KEY,
+      resource_id TEXT NOT NULL UNIQUE,
+      local_resource TEXT NOT NULL UNIQUE,
+      local_path TEXT NOT NULL UNIQUE,
+      contract TEXT NOT NULL,
+      schema_version INTEGER NOT NULL CHECK (schema_version > 0),
+      snapshot_b64 TEXT NOT NULL,
+      snapshot_checksum TEXT NOT NULL,
+      snapshot_bytes INTEGER NOT NULL CHECK (snapshot_bytes >= 0),
+      content_bytes INTEGER CHECK (content_bytes IS NULL OR content_bytes >= 0),
+      name TEXT,
+      media_type TEXT,
+      promotion_state TEXT NOT NULL DEFAULT 'pending'
+        CHECK (promotion_state IN ('pending', 'syncing', 'promoted', 'rejected')),
+      attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+      next_attempt_at TEXT,
+      last_error TEXT,
+      snapshot_key TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS shared_resource_promotions_outbox_idx
+      ON shared_resource_promotions (promotion_state, next_attempt_at, created_at);
+
+    CREATE TABLE IF NOT EXISTS shared_resource_attachments (
+      attachment_id TEXT PRIMARY KEY,
+      resource_id TEXT NOT NULL UNIQUE,
+      local_path TEXT NOT NULL UNIQUE,
+      attachment_state TEXT NOT NULL DEFAULT 'pending'
+        CHECK (attachment_state IN ('pending', 'syncing', 'attached', 'rejected')),
+      attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+      next_attempt_at TEXT,
+      last_error TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS shared_resource_attachments_outbox_idx
+      ON shared_resource_attachments (attachment_state, next_attempt_at, created_at);
+
     CREATE TABLE IF NOT EXISTS local_meta (
       key TEXT PRIMARY KEY,
       value TEXT,
@@ -466,9 +598,21 @@ function migrate(database = openLocalDb()) {
       ON browser_login_sessions(expires_at);
 
   `);
+
+  // event_log is already present on every installed machine. These nullable
+  // projection fields are additive and leave every legacy row/wire shape
+  // untouched while new SDK mutations carry their stable identity.
+  ensureColumn(database, 'event_log', 'mutation_id', 'TEXT');
+  ensureColumn(database, 'event_log', 'shared_resource_id', 'TEXT');
   require('./migrations').runLegacyMigrations(database);
 }
 
+function ensureColumn(database, tableName, columnName, declaration) {
+  const columns = database.prepare(`PRAGMA table_info(${tableName})`).all();
+  if (columns.some((column) => column.name === columnName)) return;
+  database.exec(`ALTER TABLE ${tableName} ADD COLUMN ${columnName} ${declaration}`);
+}
+
 // ---------------------------------------------------------------------------
 // Lazily created tables. The DDL lives here so this file owns every schema
 // statement, but these tables are only created when their feature is first

package/runtime/scripts/amalgm-mcp/state/docs.js

@@ -116,6 +116,10 @@ function hashText(text) {
   return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
 }
 
+function newMutationId() {
+  return `mut_${crypto.randomBytes(16).toString('base64url')}`;
+}
+
 // The only way lastDiskText is ever assigned: the hash is what persistence
 // writes, and hashing at assignment (rare: open, reconcile, flush) keeps the
 // full-text SHA-256 off the per-batch persist path. `origin` says how the
@@ -496,6 +500,42 @@ function closeDocEntry(Y, entry) {
   openDocs.delete(entry.path);
 }
 
+function recoverPendingDocMutations(Y, entry) {
+  const pending = require('./mutations').listMutations({ state: 'saving-local', limit: 1000 })
+    .filter((mutation) => mutation.localResource === entry.resource);
+  for (const mutation of pending) {
+    if (
+      mutation.operationKind !== 'yjs.update'
+      || typeof mutation.operation?.update !== 'string'
+    ) {
+      continue;
+    }
+    const bytes = Buffer.from(mutation.operation.update, 'base64');
+    try {
+      Y.decodeUpdate(new Uint8Array(bytes));
+    } catch (error) {
+      throw invalid(`cannot recover mutation ${mutation.mutationId}: ${error?.message || error}`, 500);
+    }
+    const origin = { amalgmMutation: true, source: 'recovery', patch: null };
+    Y.applyUpdate(entry.doc, new Uint8Array(bytes), origin);
+    persistDocState(Y, entry);
+    if (mutation.sharedResourceId) flushDocToDisk(Y, entry);
+    else scheduleDiskWrite(Y, entry);
+    require('./mutations').completeMaterializedMutation(
+      mutation.channelId,
+      mutation.mutationId,
+      {
+        resource: entry.resource,
+        op: 'update',
+        id: entry.path,
+        patch: origin.patch || { yjs: mutation.operation.update },
+        source: mutation.origin === 'cloud' ? 'doc:cloud-recovery' : 'doc:recovery',
+        resourceVersion: mutation.officialCloudVersion,
+      },
+    );
+  }
+}
+
 // Called before inserting a new entry: evicts down to MAX_OPEN_DOCS - 1 so
 // the insert lands exactly at the cap, never past it.
 function evictIfNeeded(Y) {
@@ -588,6 +628,14 @@ function loadDocEntry(pathInput) {
       patch.conflict = entry.pendingConflict;
       entry.pendingConflict = null;
     }
+    // SDK mutations own their journal row and event projection explicitly:
+    // durable journal first, then Y.Doc + file materialization, then event.
+    // The observer still captures the exact emitted update, but must not
+    // append an early event or schedule the shared file write after ack.
+    if (origin && typeof origin === 'object' && origin.amalgmMutation === true) {
+      origin.patch = patch;
+      return;
+    }
     appendStateEvent({
       resource: entry.resource,
       op: 'update',
@@ -603,6 +651,18 @@ function loadDocEntry(pathInput) {
   // write debounce) gets the doc written back out — never spliced over it.
   seedFromDisk(Y, entry, persisted);
 
+  // A process can die after the durable journal insert but before Y.Doc/file
+  // materialization or event projection. Replay those exact operation IDs
+  // before this open is acknowledged, so a restart cannot bury an edit.
+  try {
+    recoverPendingDocMutations(Y, entry);
+  } catch (error) {
+    if (entry.diskWriteTimer) clearTimeout(entry.diskWriteTimer);
+    if (entry.reconcileTimer) clearTimeout(entry.reconcileTimer);
+    doc.destroy();
+    throw error;
+  }
+
   evictIfNeeded(Y);
   openDocs.set(resolved, entry);
   watchDocFile(Y, entry);
@@ -761,40 +821,183 @@ function writeDocText(pathInput, textInput, options = {}) {
   return respond(merge, nextText, conflict);
 }
 
-function applyDocUpdates(pathInput, updatesInput) {
-  const Y = loadYjs();
-  const inputs = Array.isArray(updatesInput) ? updatesInput : [updatesInput];
-  if (inputs.length === 0) return { applied: 0, seq: currentSeq() };
+function normalizeDocMutations(Y, mutationsInput) {
+  const inputs = Array.isArray(mutationsInput) ? mutationsInput : [mutationsInput];
+  if (inputs.length === 0) return [];
   if (inputs.length > MAX_UPDATES_PER_CALL) {
     throw invalid(`at most ${MAX_UPDATES_PER_CALL} updates per call (got ${inputs.length})`);
   }
-  const updates = inputs.map((value, index) => {
-    if (typeof value !== 'string' || !value) {
-      throw invalid(`updates[${index}] must be a base64-encoded Yjs update`);
+  return inputs.map((input, index) => {
+    const mutationId = typeof input?.mutationId === 'string' && input.mutationId
+      ? input.mutationId
+      : newMutationId();
+    const update = input?.update;
+    if (typeof update !== 'string' || !update) {
+      throw invalid(`mutations[${index}].update must be a base64-encoded Yjs update`);
+    }
+    const bytes = Buffer.from(update, 'base64');
+    try {
+      // Decode before journaling so malformed client data remains a request
+      // error, not durable recovery work.
+      Y.decodeUpdate(new Uint8Array(bytes));
+    } catch (error) {
+      throw invalid(`invalid Yjs update: ${error?.message || error}`);
     }
-    return Buffer.from(value, 'base64');
+    return { mutationId, update, bytes };
   });
+}
 
+function applyDocMutations(pathInput, mutationsInput) {
+  const Y = loadYjs();
+  const mutations = normalizeDocMutations(Y, mutationsInput);
+  if (mutations.length === 0) return { applied: 0, seq: currentSeq(), mutationIds: [] };
   const entry = loadDocEntry(pathInput);
   entry.lastAccess = Date.now();
-  let applied = 0;
+  const results = [];
+
+  for (const mutation of mutations) {
+    const replica = require('./replicas').getReplicaByLocalResource(entry.resource);
+    const operation = { kind: 'yjs.update', update: mutation.update };
+    const origin = { amalgmMutation: true, source: 'local', patch: null };
+    const result = require('./mutations').commitLocalMutation({
+      channelId: replica ? `resource:${replica.resourceId}` : entry.resource,
+      localResource: entry.resource,
+      sharedResourceId: replica?.resourceId,
+      mutationId: mutation.mutationId,
+      deviceId: replica ? process.env.AMALGM_DEVICE_ID : null,
+      authorityEpoch: replica?.authorityEpoch || 0,
+      baseCloudVersion: replica?.appliedVersion || 0,
+      contract: replica?.contract || 'text-yjs@1',
+      schemaVersion: replica?.schemaVersion || 1,
+      operationKind: 'yjs.update',
+      operation,
+    }, {
+      materialize() {
+        Y.applyUpdate(entry.doc, new Uint8Array(mutation.bytes), origin);
+        persistDocState(Y, entry);
+        if (replica) {
+          // Shared files have a strict saved-local boundary: the user-visible
+          // file is current before the event/HTTP acknowledgement.
+          flushDocToDisk(Y, entry);
+        } else {
+          // Preserve the existing local-only write-back behavior.
+          scheduleDiskWrite(Y, entry);
+        }
+      },
+      event: () => ({
+        resource: entry.resource,
+        op: 'update',
+        id: entry.path,
+        patch: origin.patch || { yjs: mutation.update },
+        source: 'doc:update',
+      }),
+    });
+    results.push(result);
+  }
+
+  return {
+    applied: mutations.length,
+    seq: currentSeq(),
+    mutationIds: mutations.map((mutation) => mutation.mutationId),
+    states: results.map((result) => result.mutation.state),
+  };
+}
+
+function applyDocUpdates(pathInput, updatesInput) {
+  const inputs = Array.isArray(updatesInput) ? updatesInput : [updatesInput];
+  return applyDocMutations(
+    pathInput,
+    inputs.map((update) => ({ mutationId: newMutationId(), update })),
+  );
+}
+
+function applyCloudDocMutation(input) {
+  const envelope = input?.envelope || {};
+  if (envelope.operationKind !== 'yjs.update') {
+    throw invalid(`unsupported text operation ${JSON.stringify(envelope.operationKind)}`, 409);
+  }
+  const replica = require('./replicas').getReplicaByResourceId(envelope.resourceId);
+  if (!replica) throw invalid(`shared resource ${envelope.resourceId} has no local file`, 404);
+  const Y = loadYjs();
+  const [mutation] = normalizeDocMutations(Y, [{
+    mutationId: envelope.mutationId,
+    update: envelope.operation?.update,
+  }]);
+  const entry = loadDocEntry(replica.localPath);
+  if (entry.resource !== replica.localResource) {
+    throw invalid(`shared resource ${envelope.resourceId} local binding changed`, 409);
+  }
+  const origin = { amalgmMutation: true, source: 'cloud', patch: null };
+  return require('./mutations').ingestCloudMutation({
+    envelope,
+    version: input?.version,
+    committedAt: input?.committedAt,
+    localResource: entry.resource,
+  }, {
+    materialize() {
+      Y.applyUpdate(entry.doc, new Uint8Array(mutation.bytes), origin);
+      persistDocState(Y, entry);
+      // Recipient file first; the projected event that wakes its UI follows.
+      flushDocToDisk(Y, entry);
+    },
+    event: () => ({
+      resource: entry.resource,
+      op: 'update',
+      id: entry.path,
+      patch: origin.patch || { yjs: mutation.update },
+      source: 'doc:cloud',
+      resourceVersion: Number(input.version),
+    }),
+  });
+}
+
+function installCloudDocSnapshot(pathInput, input) {
+  const Y = loadYjs();
+  const snapshotBase64 = input?.snapshotBase64;
+  if (typeof snapshotBase64 !== 'string' || !snapshotBase64) {
+    throw invalid('snapshotBase64 is required');
+  }
+  const bytes = Buffer.from(snapshotBase64, 'base64');
+  const checksum = crypto.createHash('sha256').update(bytes).digest('hex');
+  if (checksum !== input?.snapshotChecksum) throw invalid('snapshot checksum mismatch', 409);
   try {
-    for (const update of updates) {
-      try {
-        Y.applyUpdate(entry.doc, new Uint8Array(update), 'client');
-      } catch (error) {
-        throw invalid(`invalid Yjs update: ${error?.message || error}`);
-      }
-      applied += 1;
-    }
-  } finally {
-    // One persist per batch, before the HTTP response acknowledges: that is
-    // the whole durability contract. It also runs when a later update in the
-    // batch is rejected — events for the applied prefix are already in the
-    // log, and the persisted state must never lag them.
-    if (applied > 0) persistDocState(Y, entry);
+    Y.decodeUpdate(new Uint8Array(bytes));
+  } catch (error) {
+    throw invalid(`invalid Yjs snapshot: ${error?.message || error}`);
+  }
+  const entry = loadDocEntry(pathInput);
+  const currentText = entry.doc.getText(TEXT_KEY).toString();
+  if (currentText.length > 0) {
+    throw invalid('cloud snapshot attachment requires an empty local text file', 409);
   }
-  return { applied: updates.length, seq: currentSeq() };
+  const origin = { amalgmMutation: true, source: 'cloud-snapshot', patch: null };
+  Y.applyUpdate(entry.doc, new Uint8Array(bytes), origin);
+  persistDocState(Y, entry);
+  flushDocToDisk(Y, entry);
+  const registered = require('./replicas').registerReplica({
+    resourceId: input?.resourceId,
+    localResource: entry.resource,
+    localPath: entry.path,
+    contract: input?.contract,
+    schemaVersion: input?.schemaVersion,
+    authorityEpoch: input?.authorityEpoch,
+    appliedVersion: input?.snapshotVersion,
+    snapshotVersion: input?.snapshotVersion,
+    snapshotChecksum: checksum,
+  });
+  // File and SQLite binding are current before a mounted UI can observe the
+  // snapshot. Applying this full Yjs state is idempotent for an already-open
+  // recipient surface.
+  const event = appendStateEvent({
+    resource: entry.resource,
+    op: 'update',
+    id: entry.path,
+    patch: origin.patch || { yjs: snapshotBase64 },
+    sharedResourceId: input.resourceId,
+    source: 'doc:cloud-snapshot',
+    resourceVersion: Number(input.snapshotVersion),
+  });
+  return { replica: registered.replica, event };
 }
 
 /**
@@ -838,10 +1041,13 @@ function closeAllDocs() {
 
 module.exports = {
   DOC_RESOURCE_PREFIX,
+  applyCloudDocMutation,
+  applyDocMutations,
   applyDocUpdates,
   closeAllDocs,
   docResourceName,
   getDocText,
+  installCloudDocSnapshot,
   openDoc,
   pathFromDocResource,
   readDocResource,