amalgm 0.1.238 → 0.1.240

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

@@ -8,12 +8,36 @@
  * is already backed by this WAL database.
  */
 
+const fs = require('fs');
 const path = require('path');
 const { ensureDir } = require('../lib/storage');
 const { LOCAL_DB_FILE, STORAGE_DIR } = require('../config');
 
 let db = null;
 
+const SHARED_RESOURCE_ATTACHMENTS_TABLE_SQL = `
+  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,
+    -- First-attachment fence: local document mutations after this cursor
+    -- are overlay work that the returned cloud snapshot cannot contain.
+    journal_cursor INTEGER NOT NULL DEFAULT 0,
+    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'))
+  );
+`;
+
+const SHARED_RESOURCE_ATTACHMENTS_INDEX_SQL = `
+  CREATE INDEX IF NOT EXISTS shared_resource_attachments_outbox_idx
+    ON shared_resource_attachments (attachment_state, next_attempt_at, created_at);
+`;
+
 // Prepared statements cached per database handle: preparing is a parse+plan
 // every time, and the realtime hot paths (event insert, replay reads, mirror
 // upserts, doc persistence) run the same fixed SQL for the process lifetime.
@@ -110,10 +134,12 @@ function migrate(database = openLocalDb()) {
         )),
       local_revision INTEGER,
       materialized_at TEXT,
+      official_projected_at TEXT,
       event_seq INTEGER,
       attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
       next_attempt_at TEXT,
       last_error TEXT,
+      failure_code 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')),
@@ -202,22 +228,6 @@ function migrate(database = openLocalDb()) {
     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,
@@ -557,6 +567,7 @@ function migrate(database = openLocalDb()) {
       device_id TEXT,
       inode TEXT,
       trashed_at TEXT,
+      trash_component_id TEXT,
       purged_at TEXT,
       missing_at TEXT,
       created_at TEXT NOT NULL,
@@ -566,7 +577,7 @@ function migrate(database = openLocalDb()) {
     );
 
     DROP INDEX IF EXISTS workspace_nodes_live_path_idx;
-    CREATE UNIQUE INDEX workspace_nodes_live_path_idx
+    CREATE UNIQUE INDEX IF NOT EXISTS workspace_nodes_live_path_idx
       ON workspace_nodes(workspace_id, relative_path)
       WHERE purged_at IS NULL AND missing_at IS NULL AND trashed_at IS NULL;
 
@@ -577,6 +588,23 @@ function migrate(database = openLocalDb()) {
       ON workspace_nodes(workspace_id, device_id, inode)
       WHERE device_id IS NOT NULL AND inode IS NOT NULL AND purged_at IS NULL;
 
+    -- A safe filesystem ambiguity is still a sync failure if it is visible
+    -- only in one observer's return value. Keep every nonterminal tree wait
+    -- durable and addressable so restart and Local Live diagnostics see the
+    -- same held state until a later observation clears it.
+    CREATE TABLE IF NOT EXISTS workspace_tree_observation_holds (
+      workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON UPDATE CASCADE ON DELETE CASCADE,
+      hold_key TEXT NOT NULL,
+      owner_kind TEXT NOT NULL DEFAULT 'observer',
+      owner_id TEXT NOT NULL DEFAULT 'workspace-tree-observer',
+      reason TEXT NOT NULL,
+      node_id TEXT,
+      operation_kind TEXT,
+      paths_json TEXT NOT NULL,
+      first_observed_at TEXT NOT NULL,
+      PRIMARY KEY (workspace_id, hold_key)
+    );
+
     CREATE TABLE IF NOT EXISTS workspace_access_state (
       workspace_id TEXT PRIMARY KEY REFERENCES workspaces(id) ON UPDATE CASCADE ON DELETE CASCADE,
       authority_epoch INTEGER NOT NULL DEFAULT 1 CHECK (authority_epoch > 0),
@@ -694,15 +722,40 @@ function migrate(database = openLocalDb()) {
       ON browser_login_sessions(expires_at);
 
   `);
+  database.exec(SHARED_RESOURCE_ATTACHMENTS_TABLE_SQL);
+  database.exec(SHARED_RESOURCE_ATTACHMENTS_INDEX_SQL);
 
   // 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');
+  ensureColumn(database, 'mutation_journal', 'failure_code', 'TEXT');
+  ensureColumn(database, 'mutation_journal', 'official_projected_at', 'TEXT');
+  ensureColumn(database, 'workspace_nodes', 'trash_component_id', 'TEXT');
+  ensureColumn(
+    database,
+    'workspace_tree_observation_holds',
+    'owner_kind',
+    "TEXT NOT NULL DEFAULT 'observer'",
+  );
+  ensureColumn(
+    database,
+    'workspace_tree_observation_holds',
+    'owner_id',
+    "TEXT NOT NULL DEFAULT 'workspace-tree-observer'",
+  );
+  backfillWorkspaceTrashComponents(database);
   // Wave-3 canaries created shared_resource_promotions before the fence
   // cursor existed.
   ensureColumn(database, 'shared_resource_promotions', 'journal_cursor', 'INTEGER NOT NULL DEFAULT 0');
+  ensureColumn(
+    database,
+    'shared_resource_attachments',
+    'journal_cursor',
+    'INTEGER NOT NULL DEFAULT 0',
+  );
+  enforceAttachmentJournalFence(database);
   ensureColumn(
     database,
     'shared_resource_replicas',
@@ -719,6 +772,108 @@ function ensureColumn(database, tableName, columnName, declaration) {
   database.exec(`ALTER TABLE ${tableName} ADD COLUMN ${columnName} ${declaration}`);
 }
 
+function backfillWorkspaceTrashComponents(database) {
+  database.prepare(`
+    UPDATE workspace_nodes
+    SET trash_component_id = NULL
+    WHERE purged_at IS NOT NULL AND trash_component_id IS NOT NULL
+  `).run();
+  const workspaces = database.prepare(
+    'SELECT id, path FROM workspaces WHERE path IS NOT NULL',
+  ).all();
+  const update = database.prepare(`
+    UPDATE workspace_nodes SET trash_component_id = ? WHERE id = ?
+  `);
+  database.transaction(() => {
+    for (const workspace of workspaces) {
+      const allRows = database.prepare(`
+        SELECT id, parent_id, trashed_at
+        FROM workspace_nodes
+        WHERE workspace_id = ? AND trashed_at IS NOT NULL AND purged_at IS NULL
+      `).all(workspace.id);
+      const nodes = new Map(allRows.map((row) => [row.id, row]));
+      const unstamped = database.prepare(`
+        SELECT id FROM workspace_nodes
+        WHERE workspace_id = ? AND trashed_at IS NOT NULL
+          AND purged_at IS NULL AND trash_component_id IS NULL
+      `).all(workspace.id);
+      for (const { id } of unstamped) {
+        const row = nodes.get(id);
+        let current = row;
+        let physicalRoot = null;
+        while (current) {
+          const candidate = path.join(
+            path.dirname(path.resolve(workspace.path)),
+            `.amalgm-tree-trash-${workspace.id}`,
+            current.id,
+          );
+          if (fs.existsSync(candidate)) {
+            physicalRoot = current.id;
+            break;
+          }
+          current = nodes.get(current.parent_id) || null;
+        }
+        // Missing physical evidence is not permission to infer ownership
+        // from a timestamp. Recovery may temporarily hold the carrier in
+        // private staging; rerun this proof after recovery or remount.
+        if (physicalRoot) update.run(physicalRoot, row.id);
+      }
+    }
+  })();
+}
+
+function enforceAttachmentJournalFence(database) {
+  const cursor = database.prepare('PRAGMA table_info(shared_resource_attachments)')
+    .all()
+    .find((column) => column.name === 'journal_cursor');
+  if (!cursor) {
+    throw new Error('shared attachment journal fence is missing');
+  }
+  database.prepare(`
+    UPDATE shared_resource_attachments
+    SET journal_cursor = 0
+    WHERE journal_cursor IS NULL
+  `).run();
+  if (cursor.notnull === 1 && String(cursor.dflt_value) === '0') return;
+
+  database.transaction(() => {
+    database.exec('DROP INDEX IF EXISTS shared_resource_attachments_outbox_idx');
+    database.exec(`
+      ALTER TABLE shared_resource_attachments
+      RENAME TO shared_resource_attachments_legacy_fence
+    `);
+    database.exec(SHARED_RESOURCE_ATTACHMENTS_TABLE_SQL);
+    database.exec(`
+      INSERT INTO shared_resource_attachments (
+        attachment_id,
+        resource_id,
+        local_path,
+        attachment_state,
+        attempt_count,
+        next_attempt_at,
+        last_error,
+        journal_cursor,
+        created_at,
+        updated_at
+      )
+      SELECT
+        attachment_id,
+        resource_id,
+        local_path,
+        attachment_state,
+        attempt_count,
+        next_attempt_at,
+        last_error,
+        COALESCE(journal_cursor, 0),
+        created_at,
+        updated_at
+      FROM shared_resource_attachments_legacy_fence
+    `);
+    database.exec('DROP TABLE shared_resource_attachments_legacy_fence');
+    database.exec(SHARED_RESOURCE_ATTACHMENTS_INDEX_SQL);
+  })();
+}
+
 // repo-card identity moved from the path to minted replica ids
 // (repo-card@2). Cards are derived observations, so the v1 table is
 // dropped rather than migrated — the next refresh rebuilds every card
@@ -764,7 +919,47 @@ function ensureDocStatesSchema(database = openLocalDb()) {
     CREATE UNIQUE INDEX IF NOT EXISTS doc_states_node_id_idx
       ON doc_states(node_id)
       WHERE node_id IS NOT NULL;
+
+    CREATE TABLE IF NOT EXISTS doc_disk_materializations (
+      channel_id TEXT NOT NULL,
+      mutation_id TEXT NOT NULL,
+      local_resource TEXT NOT NULL,
+      root TEXT NOT NULL,
+      root_dev TEXT NOT NULL,
+      root_ino TEXT NOT NULL,
+      relative_path TEXT NOT NULL,
+      transaction_id TEXT NOT NULL,
+      operation_id TEXT NOT NULL,
+      expected_json TEXT,
+      observed_text TEXT,
+      mutation_source TEXT,
+      target_json TEXT,
+      target_content BLOB,
+      plan_kind TEXT NOT NULL DEFAULT 'mutation'
+        CHECK (plan_kind IN ('mutation', 'snapshot')),
+      snapshot_payload_json TEXT,
+      snapshot_event_seq INTEGER,
+      materialization_state TEXT NOT NULL DEFAULT 'based'
+        CHECK (materialization_state IN ('based', 'prepared', 'crossed', 'superseded')),
+      successor_channel_id TEXT,
+      successor_mutation_id 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')),
+      PRIMARY KEY (channel_id, mutation_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS doc_disk_materializations_resource_idx
+      ON doc_disk_materializations(local_resource, created_at);
   `);
+  ensureColumn(
+    database,
+    'doc_disk_materializations',
+    'plan_kind',
+    "TEXT NOT NULL DEFAULT 'mutation' CHECK (plan_kind IN ('mutation', 'snapshot'))",
+  );
+  ensureColumn(database, 'doc_disk_materializations', 'snapshot_payload_json', 'TEXT');
+  ensureColumn(database, 'doc_disk_materializations', 'snapshot_event_seq', 'INTEGER');
+  ensureColumn(database, 'doc_disk_materializations', 'mutation_source', 'TEXT');
 }
 
 // App-registered resources (state/app-resources.js): the engine-side mirror
@@ -795,9 +990,13 @@ function closeLocalDb() {
 }
 
 module.exports = {
+  backfillWorkspaceTrashComponents,
   cachedStatement,
   closeLocalDb,
   ensureAppResourcesSchema,
   ensureDocStatesSchema,
   openLocalDb,
+  _private: {
+    migrate,
+  },
 };