@amalgm/shell 0.1.39 → 0.1.41

package/dist/user-ground-host.js

@@ -1,14 +1,14 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
 import { open } from "node:fs/promises";
-import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { buildUserHomeManifest, buildUserManifest, liveMachineStateDir, scopedAmalgmDir, shippedUserHomeDeclaration, } from "@amalgm/core/identity";
 import { CHUNK_BYTES, CONTENT_CONTRACT, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, deriveUploadManifest, membershipHash, parseSnapshot, pathIsSuspect, privateEntityResourceId, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
 import Database from "better-sqlite3";
 import { atomicCopy, atomicWrite, ensurePrivateDir } from "./filesystem.js";
 import { ContentCacheDownload, captureContentFile, hashContentFile, } from "./content-cache-host.js";
 import { decodeContentWireBytes, encodeContentWireBytes } from "./content-wire-codec.js";
-import { WORKSPACE_UUID as UUID, createFilesRegisterPorts, ensureWorkspaceReference, pathExists, pathWithin, referenceWorkspaceId, workspaceBindingDir, } from "./files-register-host.js";
+import { WORKSPACE_UUID as UUID, createFilesRegisterPorts, ensureWorkspaceBinding, ensureWorkspaceReference, pathExists, pathWithin, referenceWorkspaceId, workspaceBindingDir, } from "./files-register-host.js";
 import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile, hasGitMarker, } from "./git-repository-host.js";
 import { inspectGitRegistration, } from "./git-registration-host.js";
 import { projectMaterializedGraph } from "./materialized-graph.js";
@@ -57,6 +57,11 @@ export class UserGroundHost {
                     cloud: this.cloudPort(this.activeIdentity),
                     local,
                 });
+                await this.resumeWorkspaceAdds(this.activeIdentity);
+                const watchHealth = this.watchHost.health();
+                if (watchHealth.state !== "healthy") {
+                    throw new Error(`Watch coverage is degraded: ${watchHealth.reason ?? "unknown failure"}`);
+                }
                 const evidence = {
                     userId: result.userId,
                     userEmail: result.userEmail,
@@ -64,9 +69,9 @@ export class UserGroundHost {
                     localRoot: result.localRoot,
                     cloudHead: result.cloudHead,
                     mode: result.mode,
-                    entityCount: result.entityCount,
-                    watcherRoots: result.watcherRoots,
-                    watching: result.watching,
+                    entityCount: readRows(this.databasePath(this.activeIdentity)).length,
+                    watcherRoots: watchHealth.contentHandles,
+                    watching: true,
                 };
                 this.converged = true;
                 return evidence;
@@ -140,18 +145,80 @@ export class UserGroundHost {
                     references: input.references,
                     records: input.records,
                     destinationParent: input.destinationParent,
+                    cloudHead: input.cloudHead,
                     readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact),
+                    onStage: (stage) => this.options.onWorkspaceAddStage?.({
+                        workspaceId: input.workspace.uuid,
+                        stage,
+                    }),
                 });
-                this.scheduleRescan();
                 return installed;
             },
             coverWorkspace: async ({ workspaceId, baseline }) => {
-                const health = this.ensureWatchers(identity, baseline === "authoritative-install" ? [workspaceId] : []);
+                const pending = readWorkspaceAddIntent(this.databasePath(identity), workspaceId);
+                const health = this.ensureWatchers(identity, pending || baseline === "authoritative-install" ? [workspaceId] : []);
+                assertHealthyWatch(this.watchHost.evidence(), workspaceId);
+                if (pending) {
+                    await this.options.onWorkspaceAddStage?.({ workspaceId, stage: "watching" });
+                    deleteWorkspaceAddIntent(this.databasePath(identity), workspaceId);
+                }
                 return { active: true, roots: health.contentHandles };
             },
         };
         return { register, add };
     }
+    /** Resume the same host effect used by the SDK command before readiness.
+     * Staged ground has no binding, so recovery cannot race Watch or Detect. */
+    async resumeWorkspaceAdds(identity) {
+        const database = this.databasePath(identity);
+        const userRoot = this.userRoot(identity);
+        const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
+        for (const intent of readWorkspaceAddIntents(database)) {
+            const selection = workspaceAddSelection(intent);
+            const visibleAcrossBlindInterval = pathExists(intent.destinationPath);
+            const stagedAcrossBlindInterval = pathExists(intent.stagingPath);
+            if (stagedAcrossBlindInterval && readRows(database).some((row) => row.resourceId === intent.resourceId && row.rootUUID === intent.workspaceId)) {
+                // Rows prove that staging was verified before the crash, not that its
+                // bytes remained unchanged while no watcher existed. Return this
+                // private install to the intent-only stage and reproduce it from the
+                // verified immutable cache before making it visible.
+                deleteRootRows(database, intent.resourceId, intent.workspaceId);
+            }
+            await installCloudWorkspace({
+                identity,
+                userRoot,
+                database,
+                cacheDir: this.cacheDir(identity),
+                bindingDir,
+                resourceId: intent.resourceId,
+                workspace: selection.workspace,
+                reference: selection.reference,
+                references: intent.references,
+                records: intent.records,
+                destinationParent: dirname(intent.destinationPath),
+                cloudHead: intent.cloudHead,
+                readContent: (artifact) => this.downloadContent(intent.resourceId, this.cacheDir(identity), artifact),
+                onStage: (stage) => this.options.onWorkspaceAddStage?.({
+                    workspaceId: intent.workspaceId,
+                    stage,
+                }),
+            });
+            this.ensureWatchers(identity, visibleAcrossBlindInterval ? [] : [intent.workspaceId]);
+            assertHealthyWatch(this.watchHost.evidence(), intent.workspaceId);
+            if (visibleAcrossBlindInterval) {
+                // Ground that was visible while the runtime was absent may have been
+                // edited after its verified reveal. It is an ordinary startup blind
+                // interval, so Watch must retain complete suspicion and Detect must
+                // settle it before the Add responsibility can be cleared.
+                await this.flushObservedChanges();
+            }
+            await this.options.onWorkspaceAddStage?.({
+                workspaceId: intent.workspaceId,
+                stage: "watching",
+            });
+            deleteWorkspaceAddIntent(database, intent.workspaceId);
+        }
+    }
     /** Finish the user-visible register journey inside the one persistent Files
      * owner. The declaration remains durable if any later stage fails, and a
      * retry reuses its UUID through filesCommandPorts().register. */
@@ -179,7 +246,9 @@ export class UserGroundHost {
                 watch,
             };
         }
-        this.watchHost.suspectAll();
+        // Reconcile already made this newly declared root suspicious. Consume
+        // that evidence as-is: registration of one workspace must never widen
+        // uncertainty to every other root on the machine.
         this.watchDirty = false;
         try {
             await this.syncNow();
@@ -188,7 +257,6 @@ export class UserGroundHost {
                 // declaration. Preserve the declared root as suspicion and give it
                 // one scan of its own. Completion is evidence about this workspace,
                 // never a demand that unrelated live Watch traffic become silent.
-                this.watchHost.suspectAll();
                 this.watchDirty = false;
                 await this.syncNow();
             }
@@ -606,22 +674,6 @@ export class UserGroundHost {
                 materialized: true,
             });
         }
-        for (const row of readRows(this.databasePath(identity))) {
-            if (row.parentUUID !== null || row.absolutePath === root)
-                continue;
-            const directory = directoryExists(row.absolutePath)
-                ? realpathSync(row.absolutePath)
-                : resolve(row.absolutePath);
-            const prior = wanted.get(directory);
-            if (prior && prior.rootId !== row.rootUUID) {
-                throw new Error(`two logical roots claim the same Watch ground: ${directory}`);
-            }
-            wanted.set(directory, {
-                rootId: row.rootUUID,
-                directory,
-                materialized: directoryExists(directory),
-            });
-        }
         const health = this.watchHost.reconcile([...wanted.values()], {
             authoritativeBaselineRootIds,
         });
@@ -895,6 +947,11 @@ function initializeDatabase(file) {
       snapshot_json TEXT NOT NULL,
       created_at TEXT NOT NULL
     );
+    CREATE TABLE IF NOT EXISTS workspace_add_intents (
+      workspace_uuid TEXT PRIMARY KEY,
+      destination_path TEXT NOT NULL UNIQUE,
+      intent_json TEXT NOT NULL
+    );
     CREATE INDEX IF NOT EXISTS entities_by_absolute_path
       ON entities(absolute_path);
     CREATE INDEX IF NOT EXISTS entities_by_physical_identity
@@ -936,6 +993,112 @@ function readRows(file) {
         database.close();
     }
 }
+function workspaceAddStagingPath(destinationPath, workspaceId) {
+    return join(dirname(destinationPath), `.amalgm-${workspaceId}.adding`);
+}
+function workspaceAddSelection(intent) {
+    const workspace = intent.records.find((record) => record.uuid === intent.workspaceId);
+    if (!workspace || !["workspace", "folder", "repo.git"].includes(workspace.type)) {
+        throw new Error(`workspace Add intent ${intent.workspaceId} has no materialization boundary`);
+    }
+    const references = intent.references.filter((record) => record.type === "reference"
+        && record.status === "active"
+        && record.payloadVersion === intent.workspaceId);
+    if (references.length !== 1) {
+        throw new Error(`workspace Add intent ${intent.workspaceId} has no unique durable reference`);
+    }
+    return { workspace, reference: references[0] };
+}
+function parseWorkspaceAddIntent(json) {
+    const value = JSON.parse(json);
+    const workspaceId = String(value.workspaceId || "").toLowerCase();
+    const resourceId = String(value.resourceId || "");
+    const cloudHead = String(value.cloudHead || "");
+    const destinationPath = String(value.destinationPath || "");
+    const stagingPath = String(value.stagingPath || "");
+    if (!UUID.test(workspaceId) || !resourceId || !/^[0-9a-f]{64}$/i.test(cloudHead)) {
+        throw new Error("workspace Add intent identity is invalid");
+    }
+    if (!isAbsolute(destinationPath)
+        || stagingPath !== workspaceAddStagingPath(destinationPath, workspaceId)) {
+        throw new Error(`workspace Add intent ${workspaceId} has invalid placement`);
+    }
+    const intent = {
+        workspaceId,
+        resourceId,
+        cloudHead: cloudHead.toLowerCase(),
+        destinationPath,
+        stagingPath,
+        records: snapshotFromRecords(Array.isArray(value.records) ? value.records : []).records,
+        references: snapshotFromRecords(Array.isArray(value.references) ? value.references : []).records,
+    };
+    const { workspace } = workspaceAddSelection(intent);
+    if (basename(destinationPath) !== workspace.name) {
+        throw new Error(`workspace Add intent ${workspaceId} destination differs from its graph`);
+    }
+    return intent;
+}
+function readWorkspaceAddIntent(file, workspaceId) {
+    if (!existsSync(file))
+        return null;
+    const database = initializeDatabase(file);
+    try {
+        const row = database.prepare("SELECT intent_json AS intentJson FROM workspace_add_intents WHERE workspace_uuid = ?").get(workspaceId);
+        return row ? parseWorkspaceAddIntent(row.intentJson) : null;
+    }
+    finally {
+        database.close();
+    }
+}
+function readWorkspaceAddIntents(file) {
+    if (!existsSync(file))
+        return [];
+    const database = initializeDatabase(file);
+    try {
+        return database.prepare("SELECT intent_json AS intentJson FROM workspace_add_intents ORDER BY workspace_uuid").all().map(({ intentJson }) => parseWorkspaceAddIntent(intentJson));
+    }
+    finally {
+        database.close();
+    }
+}
+function persistWorkspaceAddIntent(file, proposed) {
+    const database = initializeDatabase(file);
+    try {
+        let inserted;
+        try {
+            inserted = database.prepare(`
+        INSERT INTO workspace_add_intents(workspace_uuid, destination_path, intent_json)
+        VALUES (?, ?, ?)
+        ON CONFLICT(workspace_uuid) DO NOTHING
+      `).run(proposed.workspaceId, proposed.destinationPath, stableJson(proposed));
+        }
+        catch (error) {
+            const destinationOwner = database.prepare("SELECT workspace_uuid AS workspaceId FROM workspace_add_intents WHERE destination_path = ?").get(proposed.destinationPath);
+            if (destinationOwner) {
+                throw new Error(`workspace Add destination belongs to pending workspace ${destinationOwner.workspaceId}`);
+            }
+            throw error;
+        }
+        if (inserted.changes === 1)
+            return { intent: proposed, created: true };
+        const existing = database.prepare("SELECT intent_json AS intentJson FROM workspace_add_intents WHERE workspace_uuid = ?").get(proposed.workspaceId);
+        if (!existing)
+            throw new Error(`workspace Add intent ${proposed.workspaceId} was not persisted`);
+        return { intent: parseWorkspaceAddIntent(existing.intentJson), created: false };
+    }
+    finally {
+        database.close();
+    }
+}
+function deleteWorkspaceAddIntent(file, workspaceId) {
+    const database = initializeDatabase(file);
+    try {
+        database.prepare("DELETE FROM workspace_add_intents WHERE workspace_uuid = ?").run(workspaceId);
+    }
+    finally {
+        database.close();
+    }
+}
 /** Register identity lookup is indexed and bounded: the command never walks
  * the complete entity table merely to discover that a directory is known. */
 function findKnownEntityId(file, absolutePath, deviceNumber, inode) {
@@ -1063,6 +1226,27 @@ function persistRows(file, identity, resourceId, rootUUID, rows, previousRows =
         database.close();
     }
 }
+/** A same-filesystem rename preserves identity and bytes but may advance the
+ * root directory's ctime. Refresh that one derived fingerprint before the
+ * binding makes the committed graph observable. */
+function refreshRevealedRootEvidence(file, workspaceId, absolutePath) {
+    const stats = statFingerprint(lstatSync(absolutePath));
+    const database = initializeDatabase(file);
+    try {
+        const result = database.prepare(`
+      UPDATE entities SET
+        device_number = ?, inode = ?, byte_size = ?, modified_time_ms = ?,
+        changed_time_ms = ?, filesystem_mode = ?
+      WHERE uuid = ? AND absolute_path = ?
+    `).run(stats.deviceNumber, stats.inode, stats.byteSize, stats.modifiedTimeMs, stats.changedTimeMs, stats.filesystemMode, workspaceId, absolutePath);
+        if (result.changes !== 1) {
+            throw new Error(`revealed workspace ${workspaceId} has no committed root row`);
+        }
+    }
+    finally {
+        database.close();
+    }
+}
 function assertDatabaseIdentity(file, identity) {
     const database = new Database(file, { readonly: true });
     try {
@@ -1751,6 +1935,7 @@ function installCloudGround(input) {
 async function materializeRecords(input) {
     const { records, rootPath, cacheDir, bindingDir, readContent } = input;
     const repositories = [];
+    const repositoriesByUuid = new Map();
     const fileArtifacts = new Map();
     for (const record of records) {
         if (record.type !== "file.text" && record.type !== "file.binary" && record.type !== "link")
@@ -1795,9 +1980,42 @@ async function materializeRecords(input) {
             throw new Error(`cloud repository ${record.uuid} transport does not name its declared state`);
         }
         const applied = await applyRepositoryFiles(destination, chain);
-        repositories.push({ record, state: applied });
+        const repository = { record, state: applied };
+        repositories.push(repository);
+        repositoriesByUuid.set(record.uuid, repository);
     };
     const paths = portablePaths(records, input.boundaryUUID ? new Set([input.boundaryUUID]) : new Set());
+    const recordsByUuid = new Map(records.map((record) => [record.uuid, record]));
+    const repositoryOwner = (record) => {
+        let parentUUID = record.parentUUID;
+        while (parentUUID !== null) {
+            const repository = repositoriesByUuid.get(parentUUID);
+            if (repository)
+                return repository;
+            const parent = recordsByUuid.get(parentUUID);
+            if (!parent)
+                throw new Error(`cloud entity ${record.uuid} has no parent`);
+            parentUUID = parent.parentUUID;
+        }
+        return null;
+    };
+    const assertRepositoryBoundaryPath = (record, relativePath, destination) => {
+        const owner = repositoryOwner(record);
+        if (!owner)
+            throw new Error(`cloud materialization conflicts with ${relativePath}`);
+        const ownerPath = paths.get(owner.record.uuid);
+        const repositoryPath = ownerPath
+            ? relativePath.slice(ownerPath.length + 1)
+            : relativePath;
+        const identity = owner.state.identity.find((entry) => entry.path === repositoryPath);
+        if (!identity || identity.uuid !== record.uuid || identity.type !== record.type) {
+            throw new Error(`repository boundary spine conflicts with ${relativePath}`);
+        }
+        const stats = lstatSync(destination);
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new Error(`repository boundary path is not a directory: ${relativePath}`);
+        }
+    };
     const ordered = [...records].sort((left, right) => {
         const leftPath = paths.get(left.uuid);
         const rightPath = paths.get(right.uuid);
@@ -1817,13 +2035,17 @@ async function materializeRecords(input) {
                 ensurePrivateDir(destination);
         }
         else if (record.type === "folder") {
-            if (pathExists(destination))
-                throw new Error(`cloud materialization conflicts with ${relativePath}`);
-            ensurePrivateDir(destination);
+            if (pathExists(destination)) {
+                assertRepositoryBoundaryPath(record, relativePath, destination);
+            }
+            else {
+                ensurePrivateDir(destination);
+            }
         }
         else if (record.type === "repo.git") {
-            if (pathExists(destination))
-                throw new Error(`cloud materialization conflicts with ${relativePath}`);
+            if (pathExists(destination)) {
+                assertRepositoryBoundaryPath(record, relativePath, destination);
+            }
             await materializeRepository(record, destination);
         }
         else if (record.type === "reference") {
@@ -1973,94 +2195,171 @@ function installCloudWorkspaceReferences(input) {
     return references;
 }
 async function installCloudWorkspace(input) {
-    const { identity, userRoot, database, cacheDir, bindingDir, resourceId, workspace, reference, references, records, destinationParent, readContent, } = input;
+    const { identity, userRoot, database, cacheDir, bindingDir, resourceId, workspace, reference, references, records, destinationParent, cloudHead, readContent, onStage, } = input;
     const allLocalRows = readRows(database);
     const existingBoundary = allLocalRows.find((row) => row.uuid === workspace.uuid);
     const existing = existingBoundary
         ? descendantRows(allLocalRows, workspace.uuid)
         : [];
+    const pending = readWorkspaceAddIntent(database, workspace.uuid);
     if (existing.length > 0) {
         const root = existing.find((row) => row.uuid === workspace.uuid);
-        if (!root || !pathExists(root.absolutePath)) {
+        if (!root) {
             throw new Error(`local workspace ${workspace.uuid} has unresolved placement`);
         }
+        const expectedRecords = pending?.records ?? records;
         const localRecords = existing.map((row) => Object.fromEntries(PORTABLE_FIELDS.map((field) => [field, row[field]])));
-        if (!sameRecords(travelingRecords(localRecords), records)) {
+        if (!sameRecords(travelingRecords(localRecords), expectedRecords)) {
             throw new Error(`local workspace ${workspace.uuid} differs from its cloud graph`);
         }
+        if (pending && root.absolutePath !== pending.destinationPath) {
+            throw new Error(`workspace ${workspace.uuid} rows differ from its pending destination`);
+        }
+        let revealed = false;
+        if (!pathExists(root.absolutePath)) {
+            if (!pending || !pathExists(pending.stagingPath)) {
+                throw new Error(`local workspace ${workspace.uuid} has unresolved placement`);
+            }
+            renameSync(pending.stagingPath, pending.destinationPath);
+            revealed = true;
+        }
+        else if (pending && pathExists(pending.stagingPath)) {
+            throw new Error(`workspace ${workspace.uuid} has both staged and revealed ground`);
+        }
+        if (pending && pathExists(root.absolutePath)) {
+            refreshRevealedRootEvidence(database, workspace.uuid, root.absolutePath);
+        }
+        if (revealed)
+            await onStage?.("ground-revealed");
+        ensureWorkspaceBinding({
+            bindingDir,
+            workspaceId: workspace.uuid,
+            absolutePath: root.absolutePath,
+        });
+        if (pending)
+            await onStage?.("binding-created");
+        const activeReferences = pending?.references ?? references;
+        const activeSelection = pending ? workspaceAddSelection(pending) : { workspace, reference };
         const installedReferences = installCloudWorkspaceReferences({
             identity,
             userRoot,
             database,
             bindingDir,
             resourceId,
-            workspace,
-            references,
+            workspace: activeSelection.workspace,
+            references: activeReferences,
         });
         return {
             path: root.absolutePath,
             rows: existing.length,
             records: localRecords,
-            reference,
+            reference: activeSelection.reference,
             references: installedReferences,
-            alreadyMaterialized: true,
+            alreadyMaterialized: pending === null,
         };
     }
     const parent = realpathSync(resolve(destinationParent));
     if (!statSync(parent).isDirectory())
         throw new Error("destination must be a directory");
     const destination = join(parent, workspace.name);
+    if (dirname(destination) !== parent || basename(destination) !== workspace.name) {
+        throw new Error("workspace name must be one path segment");
+    }
     const canonicalUserRoot = realpathSync(userRoot);
     if (pathWithin(canonicalUserRoot, destination) || pathWithin(destination, canonicalUserRoot)) {
         throw new Error("files add destination must be outside the Amalgm user ground");
     }
-    if (pathExists(destination))
-        throw new Error(`workspace destination already exists: ${destination}`);
     ensurePrivateDir(bindingDir);
     const binding = join(bindingDir, workspace.uuid);
-    if (pathExists(binding))
-        throw new Error(`workspace ${workspace.uuid} already has a local binding`);
-    try {
-        const materialized = await materializeRecords({
-            records,
-            rootPath: destination,
-            boundaryUUID: workspace.uuid,
-            cacheDir,
-            bindingDir,
-            readContent,
-        });
-        const rows = projectMaterializedGraph(materialized.rows, materialized.repositories.map((repository) => ({
-            record: repository.record,
-            identity: repository.state.identity,
-        })), sha256Hex);
-        symlinkSync(destination, binding, "dir");
-        persistRows(database, identity, resourceId, workspace.uuid, rows);
-        const installedReferences = installCloudWorkspaceReferences({
-            identity,
-            userRoot,
-            database,
-            bindingDir,
+    let intent = pending;
+    if (!intent) {
+        const stagingPath = workspaceAddStagingPath(destination, workspace.uuid);
+        if (pathExists(destination))
+            throw new Error(`workspace destination already exists: ${destination}`);
+        if (pathExists(stagingPath))
+            throw new Error(`workspace staging path already exists: ${stagingPath}`);
+        if (pathExists(binding))
+            throw new Error(`workspace ${workspace.uuid} already has a local binding`);
+        for (const bound of materializedWorkspaceBindings(bindingDir)) {
+            if (pathWithin(bound.directory, destination) || pathWithin(destination, bound.directory)) {
+                throw new Error(`files add destination overlaps materialized workspace ${bound.workspaceId}`);
+            }
+        }
+        const written = persistWorkspaceAddIntent(database, {
+            workspaceId: workspace.uuid,
             resourceId,
-            workspace,
-            references,
+            cloudHead,
+            destinationPath: destination,
+            stagingPath,
+            records: snapshotFromRecords(records).records,
+            references: snapshotFromRecords(references).records,
         });
-        return {
-            path: destination,
-            rows: rows.length,
-            records: rows.map((row) => row.record),
-            reference,
-            references: installedReferences,
-            alreadyMaterialized: false,
-        };
+        intent = written.intent;
+        if (written.created)
+            await onStage?.("intent-recorded");
     }
-    catch (error) {
-        deleteRootRows(database, resourceId, workspace.uuid);
-        if (pathExists(binding))
-            rmSync(binding, { force: true });
-        if (pathExists(destination))
-            rmSync(destination, { recursive: true, force: true });
-        throw error;
+    if (intent.destinationPath !== destination) {
+        throw new Error(`workspace ${workspace.uuid} already has a pending Add at ${intent.destinationPath}`);
     }
+    if (intent.resourceId !== resourceId) {
+        throw new Error(`workspace ${workspace.uuid} Add intent belongs to a different registry`);
+    }
+    if (pathExists(intent.destinationPath)) {
+        throw new Error(`workspace ${workspace.uuid} is visible without committed entity rows`);
+    }
+    if (pathExists(binding)) {
+        throw new Error(`workspace ${workspace.uuid} has a binding without committed entity rows`);
+    }
+    if (pathExists(intent.stagingPath)) {
+        rmSync(intent.stagingPath, { recursive: true, force: true });
+    }
+    const selection = workspaceAddSelection(intent);
+    const materialized = await materializeRecords({
+        records: intent.records,
+        rootPath: intent.stagingPath,
+        boundaryUUID: intent.workspaceId,
+        cacheDir,
+        bindingDir,
+        readContent,
+    });
+    const rows = projectMaterializedGraph(materialized.rows, materialized.repositories.map((repository) => ({
+        record: repository.record,
+        identity: repository.state.identity,
+    })), sha256Hex).map((row) => ({
+        ...row,
+        absolutePath: row.relativePath
+            ? join(intent.destinationPath, ...row.relativePath.split("/"))
+            : intent.destinationPath,
+    }));
+    await onStage?.("materialization-verified");
+    persistRows(database, identity, intent.resourceId, intent.workspaceId, rows);
+    await onStage?.("rows-committed");
+    renameSync(intent.stagingPath, intent.destinationPath);
+    refreshRevealedRootEvidence(database, intent.workspaceId, intent.destinationPath);
+    await onStage?.("ground-revealed");
+    ensureWorkspaceBinding({
+        bindingDir,
+        workspaceId: intent.workspaceId,
+        absolutePath: intent.destinationPath,
+    });
+    await onStage?.("binding-created");
+    const installedReferences = installCloudWorkspaceReferences({
+        identity,
+        userRoot,
+        database,
+        bindingDir,
+        resourceId: intent.resourceId,
+        workspace: selection.workspace,
+        references: intent.references,
+    });
+    return {
+        path: intent.destinationPath,
+        rows: rows.length,
+        records: rows.map((row) => row.record),
+        reference: selection.reference,
+        references: installedReferences,
+        alreadyMaterialized: false,
+    };
 }
 function readyFromFrame(frame) {
     const bytes = Buffer.from(String(frame.snapshot_b64 || ""), "base64");