@amalgm/shell 0.1.0

package/dist/user-ground-host.js

@@ -0,0 +1,809 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync, rmSync, symlinkSync, watch, writeFileSync, } from "node:fs";
+import { dirname, extname, join, sep } from "node:path";
+import { buildUserHomeManifest, buildUserManifest, liveMachineStateDir, scopedAmalgmDir, shippedUserHomeDeclaration, } from "@amalgm/core/identity";
+import { CHUNK_BYTES, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, canonicalVersion, checkContentManifest, classifyFile, convergeUserGround, createUserGroundEnrollmentPolicy, manifestFromChunks, membershipHash, parseSnapshot, snapshotFromRecords, stableJson, } from "@amalgm/live";
+import Database from "better-sqlite3";
+import { atomicWrite, ensurePrivateDir } from "./filesystem.js";
+import { WireClient, WireRequestError } from "./wire-client.js";
+const PORTABLE_FIELDS = [
+    "uuid", "type", "parentUUID", "name", "status", "version",
+    "payloadVersion", "transportVersion",
+];
+/** The production Files port injected into Core. Portable identity remains in
+ * Live; this class owns only Node filesystem, SQLite, Watch, and wire effects. */
+export class UserGroundHost {
+    options;
+    wire;
+    watchers = new Map();
+    activeIdentity = null;
+    rescanTimer = null;
+    cloudState = null;
+    syncing = null;
+    port;
+    constructor(options) {
+        this.options = options;
+        this.wire = new WireClient({
+            url: options.tunnelUrl,
+            token: options.tunnelToken,
+            runtimeVersion: options.runtimeVersion,
+        });
+        this.port = {
+            converge: async (identity) => {
+                this.activeIdentity = normalizedIdentity(identity);
+                const local = this.localPort(this.activeIdentity);
+                const result = await convergeUserGround(this.activeIdentity, {
+                    sha256Hex,
+                    cloud: this.cloudPort(this.activeIdentity),
+                    local,
+                });
+                return {
+                    userId: result.userId,
+                    userEmail: result.userEmail,
+                    deviceId: result.deviceId,
+                    localRoot: result.localRoot,
+                    cloudHead: result.cloudHead,
+                    mode: result.mode,
+                    entityCount: result.entityCount,
+                    watcherRoots: result.watcherRoots,
+                    watching: result.watching,
+                };
+            },
+        };
+    }
+    databasePath(identity) {
+        return join(liveMachineStateDir(this.userRoot(identity), identity.deviceId), "identity.db");
+    }
+    rows(identity) {
+        return readRows(this.databasePath(identity));
+    }
+    /** Make every observed filesystem change durable in SQLite, immutable
+     * content storage, and the official cloud head before returning. */
+    async flush() {
+        if (!this.activeIdentity || !this.cloudState)
+            return;
+        if (!this.syncing) {
+            this.syncing = this.syncLocalChanges(this.activeIdentity).finally(() => {
+                this.syncing = null;
+            });
+        }
+        await this.syncing;
+    }
+    async activateRuntimeTunnel(gatewayPort, runtimeToken) {
+        await this.flush();
+        this.wire.configureRuntime({ gatewayPort, runtimeToken });
+        await this.wire.open();
+    }
+    async stopRuntimeTunnel() {
+        this.wire.configureRuntime({});
+        await this.wire.close();
+    }
+    async close() {
+        await this.flush();
+        if (this.rescanTimer)
+            clearTimeout(this.rescanTimer);
+        this.rescanTimer = null;
+        for (const watcher of this.watchers.values())
+            watcher.close();
+        this.watchers.clear();
+        await this.wire.close();
+    }
+    userRoot(identity) {
+        return scopedAmalgmDir(this.options.amalgmRoot, identity.userEmail);
+    }
+    cacheDir(identity) {
+        return join(liveMachineStateDir(this.userRoot(identity), identity.deviceId), "content");
+    }
+    cloudPort(identity) {
+        return {
+            lookup: async (resourceId) => {
+                await this.drainOutboxBeforeLookup(identity, resourceId);
+                const frame = await this.wire.request({
+                    type: "private.resource.lookup",
+                    resource_id: resourceId,
+                    contract: ENTITY_CLOUD_CONTRACT,
+                }, ["private.resource.ready", "private.resource.missing"]);
+                if (frame.type === "private.resource.missing")
+                    return null;
+                const ready = readyFromFrame(frame);
+                this.cloudState = ready.state;
+                return ready.cloud;
+            },
+            publishInitial: async (input) => {
+                const bytes = Buffer.from(stableJson(input.snapshot), "utf8");
+                const frame = await this.wire.request({
+                    type: "private.resource.ensure",
+                    resource_id: input.resourceId,
+                    contract: ENTITY_CLOUD_CONTRACT,
+                    schema_version: ENTITY_CLOUD_SCHEMA_VERSION,
+                    snapshot_b64: bytes.toString("base64"),
+                    snapshot_checksum: input.checksum,
+                    snapshot_bytes: bytes.length,
+                }, ["private.resource.ready"]);
+                const ready = readyFromFrame(frame);
+                const current = ready.cloud;
+                this.cloudState = ready.state;
+                const created = frame.duplicate === false;
+                if (created)
+                    await this.uploadSnapshotContent(identity, current.resourceId, current.snapshot.records);
+                return { created, current };
+            },
+        };
+    }
+    localPort(identity) {
+        const userRoot = this.userRoot(identity);
+        const database = this.databasePath(identity);
+        const cacheDir = this.cacheDir(identity);
+        return {
+            inspect: async () => {
+                if (!existsSync(database))
+                    return null;
+                return localValue(identity, userRoot, database);
+            },
+            initialize: async () => {
+                createDeclaredHome({
+                    identity,
+                    userRoot,
+                    declaration: this.options.declaration ?? shippedUserHomeDeclaration,
+                    now: this.options.now?.() ?? new Date(),
+                });
+                scanAndRegister({ identity, userRoot, database, cacheDir });
+                return localValue(identity, userRoot, database);
+            },
+            install: async (_who, cloud) => {
+                await installCloudGround({
+                    identity,
+                    userRoot,
+                    database,
+                    cacheDir,
+                    cloud,
+                    readContent: (contentHash) => this.downloadContent(cloud.resourceId, contentHash),
+                });
+                return localValue(identity, userRoot, database);
+            },
+            watch: async () => {
+                this.ensureWatchers(identity);
+                return { active: true, roots: 1 };
+            },
+        };
+    }
+    async uploadSnapshotContent(identity, resourceId, records) {
+        const cache = this.cacheDir(identity);
+        const contentHeads = new Set(records
+            .filter((record) => ["file.text", "file.binary", "link"].includes(record.type))
+            .map((record) => record.payloadVersion)
+            .filter((head) => typeof head === "string"));
+        for (const contentHash of contentHeads) {
+            const bytes = readFileSync(join(cache, `${contentHash}.bin`));
+            if (sha256Hex(bytes) !== contentHash)
+                throw new Error(`local content ${contentHash} is corrupt`);
+            const chunks = [];
+            for (let offset = 0; offset < bytes.length; offset += CHUNK_BYTES) {
+                const part = bytes.subarray(offset, Math.min(offset + CHUNK_BYTES, bytes.length));
+                chunks.push({ sha256: sha256Hex(part), bytes: part.length, data: part });
+            }
+            const checked = manifestFromChunks(contentHash, chunks);
+            if (!checked.ok)
+                throw new Error(checked.error);
+            for (let index = 0; index < chunks.length; index += 1) {
+                const chunk = chunks[index];
+                await this.wire.request({
+                    type: "private.entity-content.put",
+                    resource_id: resourceId,
+                    content_hash: contentHash,
+                    kind: "chunk",
+                    part_index: index,
+                    part_count: chunks.length,
+                    sha256: chunk.sha256,
+                    bytes: chunk.bytes,
+                    data_b64: chunk.data.toString("base64"),
+                }, ["private.entity-content.stored"]);
+            }
+            const manifestBytes = Buffer.from(stableJson(checked.value), "utf8");
+            await this.wire.request({
+                type: "private.entity-content.put",
+                resource_id: resourceId,
+                content_hash: contentHash,
+                kind: "manifest",
+                part_index: chunks.length,
+                part_count: chunks.length,
+                sha256: sha256Hex(manifestBytes),
+                bytes: manifestBytes.length,
+                data_b64: manifestBytes.toString("base64"),
+            }, ["private.entity-content.stored"]);
+        }
+    }
+    async downloadContent(resourceId, contentHash) {
+        const manifestFrame = await retryContent(() => this.wire.request({
+            type: "private.entity-content.get",
+            resource_id: resourceId,
+            content_hash: contentHash,
+            kind: "manifest",
+            part_index: 0,
+        }, ["private.entity-content.data"]));
+        const manifestBytes = frameBytes(manifestFrame);
+        const checked = checkContentManifest(JSON.parse(manifestBytes.toString("utf8")), contentHash);
+        if (!checked.ok)
+            throw new Error(checked.error);
+        const parts = [];
+        for (let index = 0; index < checked.value.chunks.length; index += 1) {
+            const chunk = checked.value.chunks[index];
+            const frame = await this.wire.request({
+                type: "private.entity-content.get",
+                resource_id: resourceId,
+                content_hash: contentHash,
+                kind: "chunk",
+                part_index: index,
+                sha256: chunk.sha256,
+            }, ["private.entity-content.data"]);
+            const bytes = frameBytes(frame);
+            if (bytes.length !== chunk.bytes || sha256Hex(bytes) !== chunk.sha256) {
+                throw new Error(`cloud content chunk ${index} is corrupt`);
+            }
+            parts.push(bytes);
+        }
+        const bytes = Buffer.concat(parts);
+        if (bytes.length !== checked.value.bytes || sha256Hex(bytes) !== contentHash) {
+            throw new Error(`cloud content ${contentHash} is corrupt`);
+        }
+        return bytes;
+    }
+    ensureWatchers(identity) {
+        const root = this.userRoot(identity);
+        const ignoreFile = join(root, ".amalgmignore");
+        const policy = createUserGroundEnrollmentPolicy(existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "");
+        const wanted = new Set([root]);
+        const visit = (directory, base = "") => {
+            for (const entry of readdirSync(directory, { withFileTypes: true })) {
+                const rel = base ? `${base}/${entry.name}` : entry.name;
+                if (!entry.isDirectory() || entry.isSymbolicLink() || !policy(rel))
+                    continue;
+                const child = join(directory, entry.name);
+                wanted.add(child);
+                visit(child, rel);
+            }
+        };
+        visit(root);
+        for (const [directory, watcher] of this.watchers) {
+            if (!wanted.has(directory)) {
+                watcher.close();
+                this.watchers.delete(directory);
+            }
+        }
+        for (const directory of wanted) {
+            if (this.watchers.has(directory))
+                continue;
+            const watcher = watch(directory, (_event, file) => {
+                if (String(file || "").split(/[\\/]/).includes(".amalgm"))
+                    return;
+                this.scheduleRescan();
+            });
+            watcher.on("error", () => {
+                watcher.close();
+                this.watchers.delete(directory);
+            });
+            this.watchers.set(directory, watcher);
+        }
+    }
+    scheduleRescan() {
+        if (this.rescanTimer)
+            clearTimeout(this.rescanTimer);
+        this.rescanTimer = setTimeout(() => {
+            this.rescanTimer = null;
+            const identity = this.activeIdentity;
+            if (!identity)
+                return;
+            void this.flush().then(() => this.ensureWatchers(identity)).catch(() => {
+                // The durable outbox remains claimable by the next event or resume.
+            });
+        }, 150);
+        this.rescanTimer.unref();
+    }
+    async syncLocalChanges(identity) {
+        await this.drainOutbox(identity);
+        const records = scanAndRegister({
+            identity,
+            userRoot: this.userRoot(identity),
+            database: this.databasePath(identity),
+            cacheDir: this.cacheDir(identity),
+        });
+        const snapshot = snapshotFromRecords(records);
+        const checksum = sha256Hex(stableJson(snapshot));
+        if (checksum === this.cloudState?.checksum)
+            return;
+        const state = this.cloudState;
+        if (!state)
+            throw new Error("cloud state is unavailable for user-ground Watch");
+        const database = initializeDatabase(this.databasePath(identity));
+        try {
+            database.prepare(`
+        INSERT INTO cloud_outbox(
+          mutation_id, resource_id, authority_epoch, base_version,
+          snapshot_checksum, snapshot_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      `).run(randomUUID(), state.resourceId, state.authorityEpoch, state.headVersion, checksum, stableJson(snapshot), new Date().toISOString());
+        }
+        finally {
+            database.close();
+        }
+        await this.drainOutbox(identity);
+    }
+    async drainOutboxBeforeLookup(identity, resourceId) {
+        const pending = readOutbox(this.databasePath(identity));
+        if (pending.length === 0)
+            return;
+        const first = pending[0];
+        if (first.resourceId !== resourceId) {
+            throw new Error("local cloud outbox belongs to a different user-ground resource");
+        }
+        this.cloudState = {
+            resourceId: first.resourceId,
+            authorityEpoch: first.authorityEpoch,
+            headVersion: first.baseVersion,
+            checksum: "",
+        };
+        await this.drainOutbox(identity);
+    }
+    async drainOutbox(identity) {
+        for (const pending of readOutbox(this.databasePath(identity))) {
+            const snapshot = snapshotFromRecords(JSON.parse(pending.snapshotJson).records || []);
+            await this.uploadSnapshotContent(identity, pending.resourceId, snapshot.records);
+            const frame = await this.wire.request({
+                type: "shared.mutation.submit",
+                envelope: {
+                    resourceId: pending.resourceId,
+                    authorityEpoch: pending.authorityEpoch,
+                    mutationId: pending.mutationId,
+                    deviceId: identity.deviceId,
+                    baseVersion: pending.baseVersion,
+                    contract: ENTITY_CLOUD_CONTRACT,
+                    schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
+                    operationKind: "entity.snapshot.replace",
+                    operation: { kind: "entity.snapshot.replace", snapshot },
+                },
+            }, ["shared.mutation.ack"]);
+            this.cloudState = {
+                resourceId: pending.resourceId,
+                authorityEpoch: Number(frame.authority_epoch),
+                headVersion: Number(frame.version),
+                checksum: pending.snapshotChecksum,
+            };
+            deleteOutbox(this.databasePath(identity), pending.mutationId);
+        }
+    }
+}
+const sha256Hex = (input) => createHash("sha256").update(input).digest("hex");
+function normalizedIdentity(identity) {
+    return {
+        userId: String(identity.userId).trim(),
+        userEmail: String(identity.userEmail).trim().toLowerCase(),
+        deviceId: String(identity.deviceId).trim(),
+    };
+}
+function immutableWrite(file, bytes) {
+    ensurePrivateDir(dirname(file));
+    try {
+        writeFileSync(file, bytes, { mode: 0o600, flag: "wx" });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        if (!readFileSync(file).equals(Buffer.from(bytes)))
+            throw new Error(`immutable object conflict at ${file}`);
+    }
+}
+function initializeDatabase(file) {
+    ensurePrivateDir(dirname(file));
+    const database = new Database(file);
+    database.pragma("journal_mode = WAL");
+    database.pragma("synchronous = NORMAL");
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS ground_identity (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      user_id TEXT NOT NULL,
+      user_email TEXT NOT NULL,
+      device_id TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS entities (
+      uuid TEXT PRIMARY KEY,
+      type TEXT NOT NULL,
+      parent_uuid TEXT,
+      name TEXT NOT NULL,
+      status TEXT NOT NULL,
+      version TEXT NOT NULL,
+      payload_version TEXT,
+      transport_version TEXT,
+      relative_path TEXT NOT NULL UNIQUE,
+      absolute_path TEXT NOT NULL,
+      device_number INTEGER NOT NULL,
+      inode INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS cloud_outbox (
+      sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+      mutation_id TEXT NOT NULL UNIQUE,
+      resource_id TEXT NOT NULL,
+      authority_epoch INTEGER NOT NULL,
+      base_version INTEGER NOT NULL,
+      snapshot_checksum TEXT NOT NULL,
+      snapshot_json TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+  `);
+    return database;
+}
+function readRows(file) {
+    if (!existsSync(file))
+        return [];
+    const database = new Database(file, { readonly: true });
+    try {
+        return database.prepare(`
+      SELECT uuid, type, parent_uuid AS parentUUID, name, status, version,
+             payload_version AS payloadVersion, transport_version AS transportVersion,
+             relative_path AS relativePath, absolute_path AS absolutePath,
+             device_number AS deviceNumber, inode
+        FROM entities ORDER BY uuid
+    `).all();
+    }
+    finally {
+        database.close();
+    }
+}
+function readOutbox(file) {
+    if (!existsSync(file))
+        return [];
+    const database = initializeDatabase(file);
+    try {
+        return database.prepare(`
+      SELECT mutation_id AS mutationId, resource_id AS resourceId,
+             authority_epoch AS authorityEpoch, base_version AS baseVersion,
+             snapshot_checksum AS snapshotChecksum, snapshot_json AS snapshotJson
+        FROM cloud_outbox ORDER BY sequence
+    `).all();
+    }
+    finally {
+        database.close();
+    }
+}
+function deleteOutbox(file, mutationId) {
+    const database = initializeDatabase(file);
+    try {
+        database.prepare("DELETE FROM cloud_outbox WHERE mutation_id = ?").run(mutationId);
+    }
+    finally {
+        database.close();
+    }
+}
+function portableRecords(file) {
+    return readRows(file).map((row) => Object.fromEntries(PORTABLE_FIELDS.map((field) => [field, row[field]])));
+}
+function persistRows(file, identity, rows) {
+    const database = initializeDatabase(file);
+    try {
+        const replaceIdentity = database.prepare(`
+      INSERT INTO ground_identity(singleton, user_id, user_email, device_id)
+      VALUES(1, ?, ?, ?)
+      ON CONFLICT(singleton) DO UPDATE SET
+        user_id = excluded.user_id,
+        user_email = excluded.user_email,
+        device_id = excluded.device_id
+    `);
+        const insert = database.prepare(`
+      INSERT INTO entities(
+        uuid, type, parent_uuid, name, status, version, payload_version,
+        transport_version, relative_path, absolute_path, device_number, inode
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const replace = database.transaction(() => {
+            replaceIdentity.run(identity.userId, identity.userEmail, identity.deviceId);
+            database.prepare("DELETE FROM entities").run();
+            for (const row of rows)
+                insert.run(row.record.uuid, row.record.type, row.record.parentUUID, row.record.name, row.record.status, row.record.version, row.record.payloadVersion, row.record.transportVersion, row.relativePath, row.absolutePath, row.deviceNumber, row.inode);
+        });
+        replace();
+    }
+    finally {
+        database.close();
+    }
+}
+function assertDatabaseIdentity(file, identity) {
+    const database = new Database(file, { readonly: true });
+    try {
+        const found = database.prepare("SELECT user_id AS userId, user_email AS userEmail, device_id AS deviceId FROM ground_identity WHERE singleton = 1").get();
+        if (!found || found.userId !== identity.userId || found.userEmail !== identity.userEmail
+            || found.deviceId !== identity.deviceId) {
+            throw new Error("local SQLite identity does not match the authenticated user and device");
+        }
+    }
+    finally {
+        database.close();
+    }
+}
+function localValue(identity, userRoot, database) {
+    assertDatabaseIdentity(database, identity);
+    return {
+        ...identity,
+        localRoot: userRoot,
+        sqlitePath: database,
+        records: portableRecords(database),
+    };
+}
+function createDeclaredHome(input) {
+    const { identity, userRoot, declaration, now } = input;
+    ensurePrivateDir(userRoot);
+    const ignore = join(userRoot, ".amalgmignore");
+    if (!existsSync(ignore))
+        atomicWrite(ignore, "/.amalgm/\n");
+    const userManifestPath = join(userRoot, ".amalgm-user.json");
+    if (!existsSync(userManifestPath)) {
+        const manifest = buildUserManifest({ userId: identity.userId, email: identity.userEmail }, null, {
+            nowIso: () => now.toISOString(),
+        });
+        atomicWrite(userManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    }
+    const homeManifest = buildUserHomeManifest(declaration);
+    for (const root of declaration.roots)
+        ensurePrivateDir(join(userRoot, root.relativePath));
+    for (const target of declaration.exactManaged) {
+        const path = join(userRoot, target.relativePath);
+        if (target.relativePath === target.rootKey)
+            continue;
+        if (extname(path) === ".json") {
+            if (!existsSync(path)) {
+                const value = target.key === "home-manifest"
+                    ? homeManifest
+                    : { schemaVersion: 1, id: target.toolId || target.key };
+                atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`);
+            }
+        }
+        else {
+            ensurePrivateDir(path);
+        }
+    }
+}
+function fileType(bytes) {
+    return classifyFile({ binary: bytes.includes(0) });
+}
+function slashPath(path) {
+    return path.split(sep).join("/");
+}
+function scanAndRegister(input) {
+    const { identity, userRoot, database, cacheDir } = input;
+    const existingByPath = new Map(readRows(database).map((row) => [row.relativePath, row.uuid]));
+    const ignoreFile = join(userRoot, ".amalgmignore");
+    const policy = createUserGroundEnrollmentPolicy(existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "");
+    const entries = [];
+    const rootStats = lstatSync(userRoot);
+    const rootUuid = existingByPath.get("") || randomUUID();
+    entries.push({
+        uuid: rootUuid,
+        type: "workspace",
+        parentUUID: null,
+        name: identity.userEmail,
+        relativePath: "",
+        absolutePath: userRoot,
+        payloadVersion: null,
+        transportVersion: null,
+        deviceNumber: rootStats.dev,
+        inode: rootStats.ino,
+    });
+    const visit = (directory, parentUUID, base = "") => {
+        const children = readdirSync(directory, { withFileTypes: true })
+            .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+        for (const child of children) {
+            const relativePath = base ? `${base}/${child.name}` : child.name;
+            if (!policy(relativePath))
+                continue;
+            const absolutePath = join(directory, child.name);
+            const stats = lstatSync(absolutePath);
+            const uuid = existingByPath.get(relativePath) || randomUUID();
+            let type;
+            let payloadVersion = null;
+            if (stats.isSymbolicLink()) {
+                type = "link";
+                const bytes = Buffer.from(readlinkSync(absolutePath), "utf8");
+                payloadVersion = sha256Hex(bytes);
+                immutableWrite(join(cacheDir, `${payloadVersion}.bin`), bytes);
+            }
+            else if (stats.isDirectory()) {
+                type = existsSync(join(absolutePath, ".git")) ? "repo.git" : "folder";
+            }
+            else if (stats.isFile()) {
+                const bytes = readFileSync(absolutePath);
+                type = fileType(bytes);
+                payloadVersion = sha256Hex(bytes);
+                immutableWrite(join(cacheDir, `${payloadVersion}.bin`), bytes);
+            }
+            else {
+                continue;
+            }
+            entries.push({
+                uuid,
+                type,
+                parentUUID,
+                name: child.name,
+                relativePath,
+                absolutePath,
+                payloadVersion,
+                transportVersion: null,
+                deviceNumber: stats.dev,
+                inode: stats.ino,
+            });
+            if (stats.isDirectory() && !stats.isSymbolicLink())
+                visit(absolutePath, uuid, relativePath);
+        }
+    };
+    visit(userRoot, rootUuid);
+    const children = new Map();
+    for (const entry of entries) {
+        if (entry.parentUUID === null)
+            continue;
+        const group = children.get(entry.parentUUID) ?? [];
+        group.push({ uuid: entry.uuid, name: entry.name });
+        children.set(entry.parentUUID, group);
+    }
+    const rows = entries.map((entry) => {
+        const versionPayload = entry.type === "workspace" || entry.type === "folder"
+            ? membershipHash(children.get(entry.uuid) ?? [], sha256Hex)
+            : entry.payloadVersion;
+        const record = {
+            uuid: entry.uuid,
+            type: entry.type,
+            parentUUID: entry.parentUUID,
+            name: entry.name,
+            status: "active",
+            version: canonicalVersion({
+                type: entry.type,
+                parentUUID: entry.parentUUID,
+                name: entry.name,
+                status: "active",
+                payloadVersion: versionPayload,
+            }, sha256Hex),
+            payloadVersion: entry.payloadVersion,
+            transportVersion: entry.transportVersion,
+        };
+        return {
+            record,
+            relativePath: entry.relativePath,
+            absolutePath: entry.absolutePath,
+            deviceNumber: entry.deviceNumber,
+            inode: entry.inode,
+        };
+    });
+    persistRows(database, identity, rows);
+    return portableRecords(database);
+}
+function portablePaths(records) {
+    const byUuid = new Map(records.map((record) => [record.uuid, record]));
+    const memo = new Map();
+    const resolving = new Set();
+    const resolve = (record) => {
+        const found = memo.get(record.uuid);
+        if (found !== undefined)
+            return found;
+        if (resolving.has(record.uuid))
+            throw new Error("cloud user-ground graph has a parent cycle");
+        resolving.add(record.uuid);
+        let path = "";
+        if (record.parentUUID !== null) {
+            const parent = byUuid.get(record.parentUUID);
+            if (!parent)
+                throw new Error(`cloud entity ${record.uuid} has no parent`);
+            path = [resolve(parent), record.name].filter(Boolean).join("/");
+        }
+        resolving.delete(record.uuid);
+        memo.set(record.uuid, path);
+        return path;
+    };
+    for (const record of records)
+        resolve(record);
+    return memo;
+}
+function removeRegisteredPaths(userRoot, database) {
+    for (const row of readRows(database).sort((left, right) => right.relativePath.split("/").length - left.relativePath.split("/").length)) {
+        if (!row.relativePath)
+            continue;
+        const path = join(userRoot, ...row.relativePath.split("/"));
+        rmSync(path, { recursive: true, force: true });
+    }
+}
+function installCloudGround(input) {
+    const { identity, userRoot, database, cacheDir, cloud, readContent } = input;
+    return (async () => {
+        ensurePrivateDir(userRoot);
+        removeRegisteredPaths(userRoot, database);
+        const records = cloud.snapshot.records.filter((record) => record.status === "active");
+        const roots = records.filter((record) => record.parentUUID === null);
+        if (roots.length !== 1 || roots[0]?.type !== "workspace") {
+            throw new Error("cloud user ground must have exactly one workspace root");
+        }
+        const paths = portablePaths(records);
+        const ordered = [...records].sort((left, right) => {
+            const leftPath = paths.get(left.uuid);
+            const rightPath = paths.get(right.uuid);
+            return leftPath.split("/").length - rightPath.split("/").length
+                || (leftPath < rightPath ? -1 : leftPath > rightPath ? 1 : 0);
+        });
+        for (const record of ordered) {
+            const relativePath = paths.get(record.uuid);
+            const destination = relativePath ? join(userRoot, ...relativePath.split("/")) : userRoot;
+            if (record.parentUUID === null) {
+                ensurePrivateDir(destination);
+            }
+            else if (record.type === "folder") {
+                if (existsSync(destination))
+                    throw new Error(`cloud materialization conflicts with ${relativePath}`);
+                ensurePrivateDir(destination);
+            }
+            else if (["file.text", "file.binary", "link"].includes(record.type)) {
+                if (!record.payloadVersion)
+                    throw new Error(`cloud leaf ${record.uuid} has no content head`);
+                if (existsSync(destination))
+                    throw new Error(`cloud materialization conflicts with ${relativePath}`);
+                const bytes = await readContent(record.payloadVersion);
+                ensurePrivateDir(dirname(destination));
+                if (record.type === "link")
+                    symlinkSync(bytes.toString("utf8"), destination);
+                else
+                    atomicWrite(destination, bytes);
+                immutableWrite(join(cacheDir, `${record.payloadVersion}.bin`), bytes);
+            }
+            else {
+                throw new Error(`materialization for ${record.type} requires its dedicated adapter`);
+            }
+        }
+        const rows = records.map((record) => {
+            const relativePath = paths.get(record.uuid);
+            const absolutePath = relativePath ? join(userRoot, ...relativePath.split("/")) : userRoot;
+            const stats = lstatSync(absolutePath);
+            return {
+                record,
+                relativePath,
+                absolutePath,
+                deviceNumber: stats.dev,
+                inode: stats.ino,
+            };
+        });
+        persistRows(database, identity, rows);
+    })();
+}
+function readyFromFrame(frame) {
+    const bytes = Buffer.from(String(frame.snapshot_b64 || ""), "base64");
+    const cloud = {
+        resourceId: String(frame.resource_id || ""),
+        version: Number(frame.head_version),
+        checksum: String(frame.snapshot_checksum || ""),
+        snapshot: parseSnapshot(bytes),
+    };
+    return {
+        cloud,
+        state: {
+            resourceId: cloud.resourceId,
+            authorityEpoch: Number(frame.authority_epoch),
+            headVersion: cloud.version,
+            checksum: cloud.checksum,
+        },
+    };
+}
+function frameBytes(frame) {
+    const bytes = Buffer.from(String(frame.data_b64 || ""), "base64");
+    if (bytes.length !== Number(frame.bytes) || sha256Hex(bytes) !== String(frame.sha256 || "")) {
+        throw new Error("wire content bytes do not match their checksum");
+    }
+    return bytes;
+}
+async function retryContent(read) {
+    let last;
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        try {
+            return await read();
+        }
+        catch (error) {
+            last = error;
+            if (!(error instanceof WireRequestError) || error.code !== "entity_content_not_found")
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 250 * (attempt + 1)));
+        }
+    }
+    throw last;
+}
+//# sourceMappingURL=user-ground-host.js.map