@amalgm/shell 0.1.18 → 0.1.20

package/dist/user-ground-host.js

@@ -3,10 +3,12 @@ import { createReadStream, existsSync, lstatSync, realpathSync, readFileSync, re
 import { open } from "node:fs/promises";
 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, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, membershipHash, parseSnapshot, privateEntityResourceId, sameRecords, snapshotFromRecords, stableJson, travelingRecords, unpack, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
+import { CHUNK_BYTES, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, convergeUserGround, createSuspicionScope, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, membershipHash, parseSnapshot, pathIsSuspect, privateEntityResourceId, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
 import Database from "better-sqlite3";
-import { atomicWrite, ensurePrivateDir } from "./filesystem.js";
-import { applyRepository, captureRepository, isRepository, } from "./git-repository-host.js";
+import { atomicAssemble, atomicCopy, atomicWrite, ensurePrivateDir } from "./filesystem.js";
+import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile, isRepository, } from "./git-repository-host.js";
+import { inspectGitRegistration, } from "./git-registration-host.js";
+import { projectMaterializedGraph } from "./materialized-graph.js";
 import { WireClient, WireRequestError } from "./wire-client.js";
 const PORTABLE_FIELDS = [
     "uuid", "type", "parentUUID", "name", "status", "version",
@@ -25,6 +27,7 @@ export class UserGroundHost {
     cloudState = null;
     converged = false;
     syncing = null;
+    closing = false;
     port;
     constructor(options) {
         this.options = options;
@@ -179,8 +182,16 @@ export class UserGroundHost {
     async flush() {
         if (!this.converged || !this.activeIdentity || !this.cloudState)
             return;
-        this.watchDirty = false;
+        const identity = this.activeIdentity;
+        for (const watcher of this.watchers.values())
+            watcher.suspicion.suspectAll();
+        this.watchDirty = true;
         await this.syncNow();
+        if (!this.closing)
+            this.ensureWatchers(identity);
+        await this.flushObservedChanges();
+        if (!this.closing)
+            this.ensureWatchers(identity);
         await this.flushObservedChanges();
     }
     async syncNow() {
@@ -194,14 +205,20 @@ export class UserGroundHost {
         await this.syncing;
     }
     async flushObservedChanges() {
-        do {
-            const dirty = this.watchDirty;
+        while (true) {
+            const dirty = this.watchDirty
+                || [...this.watchers.values()].some((watcher) => watcher.suspicion.size > 0);
             this.watchDirty = false;
-            if (dirty)
+            if (dirty) {
                 await this.syncNow();
-            else if (this.syncing)
+                continue;
+            }
+            if (this.syncing) {
                 await this.syncing;
-        } while (this.watchDirty);
+                continue;
+            }
+            return;
+        }
     }
     async activateRuntimeTunnel(gatewayPort, runtimeToken) {
         await this.flush();
@@ -213,12 +230,18 @@ export class UserGroundHost {
         await this.wire.close();
     }
     async close() {
+        // Command shutdown is the last catch-up boundary. A filesystem callback
+        // may still be queued, so watcher silence cannot be used as evidence yet.
+        for (const watcher of this.watchers.values())
+            watcher.suspicion.suspectAll();
+        this.watchDirty = this.watchers.size > 0 || this.watchDirty;
+        this.closing = true;
         if (this.rescanTimer)
             clearTimeout(this.rescanTimer);
         this.rescanTimer = null;
         await this.flushObservedChanges();
         for (const watcher of this.watchers.values())
-            watcher.close();
+            watcher.handle.close();
         this.watchers.clear();
         if (this.rescanTimer)
             clearTimeout(this.rescanTimer);
@@ -338,32 +361,23 @@ export class UserGroundHost {
                 }, {
                     sha256Hex,
                     missingChunks: async (_candidate, manifest) => {
-                        try {
-                            const frame = await retryContent(() => this.wire.request({
-                                type: "private.entity-content.get",
-                                resource_id: resourceId,
-                                content_hash: artifact.contentHash,
-                                kind: "manifest",
-                                part_index: 0,
-                            }, ["private.entity-content.data"]));
-                            const found = checkContentManifest(JSON.parse(frameBytes(frame).toString("utf8")), artifact.contentHash);
-                            if (!found.ok)
-                                throw new Error(found.error);
-                            manifestPresent = true;
-                            return [];
-                        }
-                        catch (error) {
-                            if (error instanceof WireRequestError && error.code === "entity_content_not_found") {
-                                return manifest.chunks.map((_chunk, index) => index);
-                            }
-                            throw error;
+                        const frame = await retryContent(() => this.wire.request({
+                            type: "private.entity-content.inventory",
+                            resource_id: resourceId,
+                            content_hash: artifact.contentHash,
+                            chunks: manifest.chunks,
+                        }, ["private.entity-content.inventory-result"]));
+                        manifestPresent = frame.complete === true;
+                        if (!Array.isArray(frame.missing)) {
+                            throw new Error("content authority returned an invalid inventory");
                         }
+                        return frame.missing;
                     },
                     putChunk: async (_candidate, manifest, index, bytes) => {
                         const chunk = manifest.chunks[index];
                         if (!chunk)
                             throw new Error(`content manifest has no chunk ${index}`);
-                        await retryContent(() => this.wire.request({
+                        await retryContent(() => this.wire.requestBinary({
                             type: "private.entity-content.put",
                             resource_id: resourceId,
                             content_hash: artifact.contentHash,
@@ -372,14 +386,13 @@ export class UserGroundHost {
                             part_count: manifest.chunks.length,
                             sha256: chunk.sha256,
                             bytes: chunk.bytes,
-                            data_b64: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64"),
-                        }, ["private.entity-content.stored"]));
+                        }, bytes, ["private.entity-content.stored"]));
                     },
                     putManifest: async (_candidate, manifest) => {
                         if (manifestPresent)
                             return;
                         const bytes = Buffer.from(stableJson(manifest), "utf8");
-                        await retryContent(() => this.wire.request({
+                        await retryContent(() => this.wire.requestBinary({
                             type: "private.entity-content.put",
                             resource_id: resourceId,
                             content_hash: artifact.contentHash,
@@ -388,8 +401,7 @@ export class UserGroundHost {
                             part_count: manifest.chunks.length,
                             sha256: sha256Hex(bytes),
                             bytes: bytes.length,
-                            data_b64: bytes.toString("base64"),
-                        }, ["private.entity-content.stored"]));
+                        }, bytes, ["private.entity-content.stored"]));
                     },
                 });
                 atomicWrite(manifestCacheFile(cache, artifact.contentHash), stableJson(receipt.manifest));
@@ -444,40 +456,34 @@ export class UserGroundHost {
                 atomicWrite(chunkCacheFile(cacheDir, chunk.sha256), bytes);
             },
             sealArtifact: async (_candidate, manifest) => {
-                const bytes = Buffer.concat(manifest.chunks.map((chunk) => readFileSync(chunkCacheFile(cacheDir, chunk.sha256))));
-                const contentHash = sha256Hex(bytes);
-                if (bytes.length !== manifest.bytes || contentHash !== manifest.contentHash) {
+                const file = contentCacheFile(cacheDir, artifact.contentHash);
+                const sealed = await atomicAssemble(file, manifest.chunks.map((chunk) => chunkCacheFile(cacheDir, chunk.sha256)));
+                if (sealed.bytes !== manifest.bytes || sealed.sha256 !== manifest.contentHash) {
                     throw new Error(`cloud content ${artifact.contentHash} is corrupt`);
                 }
-                atomicWrite(contentCacheFile(cacheDir, artifact.contentHash), bytes);
                 atomicWrite(manifestCacheFile(cacheDir, artifact.contentHash), stableJson(manifest));
-                return { local: bytes, bytes: bytes.length, contentHash };
+                return {
+                    local: { file, bytes: sealed.bytes, contentHash: sealed.sha256 },
+                    bytes: sealed.bytes,
+                    contentHash: sealed.sha256,
+                };
             },
         });
         return receipt.local;
     }
     ensureWatchers(identity) {
+        if (this.closing)
+            return;
         const root = this.userRoot(identity);
         const ignoreFile = join(root, ".amalgmignore");
         const policy = createUserGroundEnrollmentPolicy(existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "");
-        const wanted = new Set();
-        const visit = (directory, enrollment, base = "") => {
-            wanted.add(directory);
-            for (const entry of readdirSync(directory, { withFileTypes: true })) {
-                const rel = base ? `${base}/${entry.name}` : entry.name;
-                if (!entry.isDirectory() || entry.isSymbolicLink() || !enrollment(rel))
-                    continue;
-                const child = join(directory, entry.name);
-                visit(child, enrollment, rel);
-            }
-        };
-        visit(root, policy);
+        const wanted = new Map([[root, policy]]);
         for (const row of readRows(this.databasePath(identity))) {
             if (row.parentUUID !== null || row.absolutePath === root)
                 continue;
             try {
                 if (statSync(row.absolutePath).isDirectory())
-                    visit(row.absolutePath, () => true);
+                    wanted.set(row.absolutePath, () => true);
             }
             catch {
                 // Unresolved ground keeps its rows but cannot hold a watcher handle.
@@ -485,35 +491,62 @@ export class UserGroundHost {
         }
         for (const [directory, watcher] of this.watchers) {
             if (!wanted.has(directory)) {
-                watcher.close();
+                watcher.handle.close();
                 this.watchers.delete(directory);
             }
         }
-        for (const directory of wanted) {
+        for (const [directory, enrollment] of wanted) {
             if (this.watchers.has(directory))
                 continue;
-            const watcher = watch(directory, (_event, file) => {
-                if (String(file || "").split(/[\\/]/).includes(".amalgm"))
+            const suspicion = createSuspicionScope();
+            const handle = watch(directory, { recursive: true }, (_event, file) => {
+                const relativePath = String(file || "").split(sep).join("/");
+                if (relativePath.split("/").includes(".amalgm"))
+                    return;
+                if (relativePath && !enrollment(relativePath))
                     return;
+                const segments = relativePath.split("/");
+                const git = segments.indexOf(".git");
+                if (!relativePath || relativePath === ".amalgmignore"
+                    || (git === 0 && segments[1] === "index")) {
+                    suspicion.suspectAll();
+                }
+                else if (git > 0 && segments[git + 1] === "index") {
+                    suspicion.ring(segments.slice(0, git).join("/"));
+                }
+                else {
+                    suspicion.ring(relativePath);
+                }
                 this.scheduleRescan();
             });
-            watcher.on("error", () => {
-                watcher.close();
+            handle.on("error", () => {
+                suspicion.suspectAll();
+                handle.close();
                 this.watchers.delete(directory);
+                this.scheduleRescan();
             });
-            this.watchers.set(directory, watcher);
+            this.watchers.set(directory, { handle, suspicion });
+            // Coverage began after the preceding observation. One catch-up proves
+            // the unobserved interval before watcher silence can be trusted.
+            suspicion.suspectAll();
+            this.scheduleRescan();
         }
     }
     scheduleRescan() {
+        if (this.closing)
+            return;
         this.watchDirty = true;
         if (this.rescanTimer)
             clearTimeout(this.rescanTimer);
         this.rescanTimer = setTimeout(() => {
             this.rescanTimer = null;
             const identity = this.activeIdentity;
-            if (!identity)
+            if (!identity || this.closing)
                 return;
-            void this.flushObservedChanges().then(() => this.ensureWatchers(identity)).catch(() => {
+            void this.flushObservedChanges().then(() => {
+                if (!this.closing)
+                    this.ensureWatchers(identity);
+            }).catch(() => {
                 // The durable outbox remains claimable by the next event or resume.
             });
         }, 150);
@@ -524,16 +557,25 @@ export class UserGroundHost {
         const state = this.cloudState;
         if (!state)
             throw new Error("cloud state is unavailable for user-ground Watch");
+        const observations = new Map();
+        for (const [directory, watcher] of this.watchers) {
+            observations.set(directory, watcher.suspicion.snapshot());
+        }
         const localRecords = scanAndRegister({
             identity,
             userRoot: this.userRoot(identity),
             database: this.databasePath(identity),
             cacheDir: this.cacheDir(identity),
+            suspicions: new Map([...observations].map(([directory, snapshot]) => [directory, snapshot.paths])),
         });
         const snapshot = snapshotFromRecords(travelingRecords(mergeMaterializedRoots(state.records, localRecords)));
         const checksum = sha256Hex(stableJson(snapshot));
-        if (checksum === state.checksum)
+        if (checksum === state.checksum) {
+            for (const [directory, snapshot] of observations) {
+                this.watchers.get(directory)?.suspicion.settle(snapshot);
+            }
             return;
+        }
         const database = initializeDatabase(this.databasePath(identity));
         try {
             database.prepare(`
@@ -547,6 +589,9 @@ export class UserGroundHost {
             database.close();
         }
         await this.drainOutbox(identity);
+        for (const [directory, snapshot] of observations) {
+            this.watchers.get(directory)?.suspicion.settle(snapshot);
+        }
     }
     async drainOutboxBeforeLookup(identity, resourceId) {
         const pending = readOutbox(this.databasePath(identity));
@@ -780,10 +825,13 @@ function deleteOutbox(file, mutationId) {
         database.close();
     }
 }
+function portableRecord(row) {
+    return Object.fromEntries(PORTABLE_FIELDS.map((field) => [field, row[field]]));
+}
 function portableRecords(file) {
-    return readRows(file).map((row) => Object.fromEntries(PORTABLE_FIELDS.map((field) => [field, row[field]])));
+    return readRows(file).map(portableRecord);
 }
-function persistRows(file, identity, resourceId, rootUUID, rows) {
+function persistRows(file, identity, resourceId, rootUUID, rows, previousRows = []) {
     const database = initializeDatabase(file);
     try {
         const replaceIdentity = database.prepare(`
@@ -794,18 +842,54 @@ function persistRows(file, identity, resourceId, rootUUID, rows) {
         user_email = excluded.user_email,
         device_id = excluded.device_id
     `);
-        const insert = database.prepare(`
+        const upsert = database.prepare(`
       INSERT INTO entities(
         uuid, resource_id, root_uuid, type, parent_uuid, name, status, version, payload_version,
         transport_version, relative_path, absolute_path, device_number, inode
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(uuid) DO UPDATE SET
+        resource_id = excluded.resource_id,
+        root_uuid = excluded.root_uuid,
+        type = excluded.type,
+        parent_uuid = excluded.parent_uuid,
+        name = excluded.name,
+        status = excluded.status,
+        version = excluded.version,
+        payload_version = excluded.payload_version,
+        transport_version = excluded.transport_version,
+        relative_path = excluded.relative_path,
+        absolute_path = excluded.absolute_path,
+        device_number = excluded.device_number,
+        inode = excluded.inode
     `);
+        const remove = database.prepare("DELETE FROM entities WHERE uuid = ? AND resource_id = ? AND root_uuid = ?");
+        const previousByUuid = new Map(previousRows.map((row) => [row.uuid, row]));
+        const currentUuids = new Set(rows.map((row) => row.record.uuid));
+        const changed = rows.filter((row) => {
+            const old = previousByUuid.get(row.record.uuid);
+            return !old
+                || old.resourceId !== resourceId
+                || old.rootUUID !== rootUUID
+                || old.type !== row.record.type
+                || old.parentUUID !== row.record.parentUUID
+                || old.name !== row.record.name
+                || old.status !== row.record.status
+                || old.version !== row.record.version
+                || old.payloadVersion !== row.record.payloadVersion
+                || old.transportVersion !== row.record.transportVersion
+                || old.relativePath !== row.relativePath
+                || old.absolutePath !== row.absolutePath
+                || old.deviceNumber !== row.deviceNumber
+                || old.inode !== row.inode;
+        });
         const replace = database.transaction(() => {
             replaceIdentity.run(identity.userId, identity.userEmail, identity.deviceId);
-            database.prepare("DELETE FROM entities WHERE resource_id = ? AND root_uuid = ?")
-                .run(resourceId, rootUUID);
-            for (const row of rows)
-                insert.run(row.record.uuid, resourceId, rootUUID, 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);
+            for (const old of previousRows) {
+                if (!currentUuids.has(old.uuid))
+                    remove.run(old.uuid, resourceId, rootUUID);
+            }
+            for (const row of changed)
+                upsert.run(row.record.uuid, resourceId, rootUUID, 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();
     }
@@ -875,12 +959,17 @@ function slashPath(path) {
     return path.split(sep).join("/");
 }
 function scanAndRegister(input) {
-    const { identity, userRoot, database, cacheDir } = input;
+    const { identity, userRoot, database, cacheDir, suspicions } = input;
     const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
     const existing = readRows(database);
     const ignoreFile = join(userRoot, ".amalgmignore");
     const policy = createUserGroundEnrollmentPolicy(existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "");
     const bindingDir = workspaceBindingDir(userRoot, identity.deviceId);
+    const suspicionFor = (root) => {
+        if (!suspicions || !suspicions.has(root))
+            return suspicions ? [] : null;
+        return suspicions.get(root);
+    };
     const existingCore = existing.find((row) => row.parentUUID === null && row.absolutePath === userRoot && row.type === "workspace");
     const coreUUID = existingCore?.uuid || randomUUID();
     const core = scanRoot({
@@ -894,9 +983,11 @@ function scanAndRegister(input) {
         cacheDir,
         policy,
         bindingDir,
+        suspects: suspicionFor(userRoot),
+        existingRows: existing.filter((row) => row.rootUUID === coreUUID),
     });
     const targetRoots = new Set(core.referenceWorkspaceIds);
-    for (const row of readRows(database)) {
+    for (const row of existing) {
         if (row.parentUUID === null && row.uuid !== coreUUID)
             targetRoots.add(row.uuid);
     }
@@ -914,7 +1005,8 @@ function scanAndRegister(input) {
             // so a move can be rescued; absence is never permission to delete it.
             continue;
         }
-        const existingRoot = readRows(database).find((row) => row.uuid === workspaceId && row.parentUUID === null);
+        const existingRoot = existing.find((row) => row.uuid === workspaceId && row.parentUUID === null);
+        const existingWorkspaceRows = existing.filter((row) => row.rootUUID === workspaceId);
         scanRoot({
             identity,
             resourceId,
@@ -926,15 +1018,32 @@ function scanAndRegister(input) {
             cacheDir,
             policy: () => true,
             bindingDir,
+            suspects: existingWorkspaceRows.length === 0 ? null : suspicionFor(rootPath),
+            existingRows: existingWorkspaceRows,
         });
     }
     return portableRecords(database);
 }
 function scanRoot(input) {
-    const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, seedByPath = new Map(), repositoryHeads = new Map(), persist = true, } = input;
-    const existingByPath = new Map(readRows(database)
-        .filter((row) => row.resourceId === resourceId && row.rootUUID === rootUUID)
-        .map((row) => [row.relativePath, row]));
+    const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, suspects = null, } = input;
+    const existingRows = (input.existingRows ?? readRows(database))
+        .filter((row) => row.resourceId === resourceId && row.rootUUID === rootUUID);
+    const existingByPath = new Map(existingRows.map((row) => [row.relativePath, row]));
+    if (suspects !== null && suspects.length === 0 && existingRows.length > 0) {
+        return {
+            records: existingRows.map(portableRecord),
+            rows: existingRows.map((row) => ({
+                record: portableRecord(row),
+                relativePath: row.relativePath,
+                absolutePath: row.absolutePath,
+                deviceNumber: row.deviceNumber,
+                inode: row.inode,
+            })),
+            referenceWorkspaceIds: existingRows
+                .filter((row) => row.type === "reference" && row.payloadVersion && UUID.test(row.payloadVersion))
+                .map((row) => row.payloadVersion),
+        };
+    }
     const entries = [];
     const referenceWorkspaceIds = new Set();
     const rootStats = lstatSync(rootPath);
@@ -950,7 +1059,33 @@ function scanRoot(input) {
         deviceNumber: rootStats.dev,
         inode: rootStats.ino,
     });
-    const visit = (directory, parentUUID, parentType, base = "") => {
+    const touchesSuspicion = (path) => suspects === null
+        || pathIsSuspect(path, suspects)
+        || suspects.some((suspect) => suspect.startsWith(`${path}/`));
+    const repositoryEvidencePaths = (repository) => {
+        if (suspects === null)
+            return null;
+        const prefix = slashPath(relative(rootPath, repository));
+        const paths = [];
+        for (const suspect of suspects) {
+            if (suspect === prefix || (prefix && prefix.startsWith(`${suspect}/`)))
+                return null;
+            const local = prefix
+                ? suspect.startsWith(`${prefix}/`) ? suspect.slice(prefix.length + 1) : null
+                : suspect;
+            if (local === null)
+                continue;
+            if (local === ".git/index" || local.startsWith(".git/index/"))
+                return null;
+            if (local === ".git" || local.startsWith(".git/"))
+                continue;
+            paths.push(local);
+        }
+        return [...new Set(paths)].sort();
+    };
+    const visit = (directory, parentUUID, parentType, base = "", activeRepository = parentType === "repo.git"
+        ? { root: directory, evidencePaths: repositoryEvidencePaths(directory), evidence: null }
+        : null) => {
         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) {
@@ -962,11 +1097,27 @@ function scanRoot(input) {
             const absolutePath = join(directory, child.name);
             const stats = lstatSync(absolutePath);
             const existing = existingByPath.get(relativePath);
-            const seeded = seedByPath.get(relativePath);
-            const uuid = existing?.uuid || seeded?.uuid || randomUUID();
+            const uuid = existing?.uuid || randomUUID();
+            const observe = existing === undefined || touchesSuspicion(relativePath);
+            const repositoryPath = activeRepository
+                ? slashPath(relative(activeRepository.root, absolutePath))
+                : null;
+            if (observe && repositoryPath && activeRepository && !activeRepository.evidence) {
+                activeRepository.evidence = inspectGitRegistration(activeRepository.root, activeRepository.evidencePaths);
+            }
+            const indexed = observe && repositoryPath
+                ? activeRepository?.evidence?.cleanLeaves.get(repositoryPath)
+                : undefined;
             let type;
             let payloadVersion = null;
-            if (stats.isSymbolicLink()) {
+            if (!observe && existing) {
+                type = existing.type;
+                payloadVersion = existing.payloadVersion;
+                if (type === "reference" && payloadVersion && UUID.test(payloadVersion)) {
+                    referenceWorkspaceIds.add(payloadVersion);
+                }
+            }
+            else if (stats.isSymbolicLink()) {
                 const referenceId = referenceWorkspaceId(absolutePath, bindingDir);
                 if (referenceId) {
                     type = "reference";
@@ -975,28 +1126,36 @@ function scanRoot(input) {
                 }
                 else {
                     type = "link";
-                    const bytes = Buffer.from(readlinkSync(absolutePath), "utf8");
-                    payloadVersion = sha256Hex(bytes);
-                    immutableWrite(join(cacheDir, `${payloadVersion}.bin`), bytes);
+                    if (indexed?.type === "link") {
+                        payloadVersion = indexed.payloadVersion;
+                    }
+                    else {
+                        const bytes = Buffer.from(readlinkSync(absolutePath), "utf8");
+                        payloadVersion = sha256Hex(bytes);
+                        if (!activeRepository)
+                            immutableWrite(join(cacheDir, `${payloadVersion}.bin`), bytes);
+                    }
                 }
             }
             else if (stats.isDirectory()) {
                 type = classifyDirectory({ repository: isRepository(absolutePath) });
             }
             else if (stats.isFile()) {
-                const bytes = readFileSync(absolutePath);
-                type = fileType(bytes);
-                payloadVersion = sha256Hex(bytes);
-                immutableWrite(join(cacheDir, `${payloadVersion}.bin`), bytes);
+                if (indexed && indexed.type !== "link") {
+                    type = indexed.type;
+                    payloadVersion = indexed.payloadVersion;
+                }
+                else {
+                    const bytes = readFileSync(absolutePath);
+                    type = fileType(bytes);
+                    payloadVersion = sha256Hex(bytes);
+                    if (!activeRepository)
+                        immutableWrite(join(cacheDir, `${payloadVersion}.bin`), bytes);
+                }
             }
             else {
                 continue;
             }
-            if (seeded && seeded.type !== type
-                && !(["file.text", "file.binary"].includes(seeded.type)
-                    && ["file.text", "file.binary"].includes(type))) {
-                throw new Error(`materialized entity ${relativePath} is ${type}, expected ${seeded.type}`);
-            }
             entries.push({
                 uuid,
                 type,
@@ -1010,7 +1169,13 @@ function scanRoot(input) {
                 inode: stats.ino,
             });
             if (stats.isDirectory() && !stats.isSymbolicLink()) {
-                visit(absolutePath, uuid, type, relativePath);
+                visit(absolutePath, uuid, type, relativePath, type === "repo.git"
+                    ? {
+                        root: absolutePath,
+                        evidencePaths: repositoryEvidencePaths(absolutePath),
+                        evidence: null,
+                    }
+                    : activeRepository);
             }
         }
     };
@@ -1030,42 +1195,60 @@ function scanRoot(input) {
                 : entry.relativePath,
             uuid: entry.uuid,
             type: entry.type,
+            payloadVersion: entry.payloadVersion,
         }))
             .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
-        const seededHead = repositoryHeads.get(repository.uuid);
-        if (seededHead) {
-            if (sha256Hex(seededHead.bytes) !== seededHead.transportVersion) {
-                throw new Error(`repository transport ${repository.uuid} is corrupt`);
-            }
-            const state = unpack(Buffer.from(seededHead.bytes).toString("utf8"));
-            if (state.stateId !== seededHead.stateId
-                || JSON.stringify(state.identity ?? []) !== JSON.stringify(repoIdentity)) {
-                throw new Error(`repository transport ${repository.uuid} does not match its materialized identity`);
-            }
-            repository.payloadVersion = seededHead.stateId;
-            repository.transportVersion = seededHead.transportVersion;
-            immutableWrite(join(cacheDir, `${seededHead.transportVersion}.bin`), seededHead.bytes);
-            continue;
-        }
         const priorRow = existingByPath.get(repository.relativePath);
         let prior = null;
         if (priorRow?.type === "repo.git" && priorRow.payloadVersion && priorRow.transportVersion) {
             const priorPath = join(cacheDir, `${priorRow.transportVersion}.bin`);
             if (existsSync(priorPath)) {
-                const bytes = readFileSync(priorPath);
-                if (sha256Hex(bytes) === priorRow.transportVersion) {
-                    prior = {
-                        stateId: priorRow.payloadVersion,
-                        transportVersion: priorRow.transportVersion,
-                        bytes,
-                    };
+                try {
+                    const layout = inspectRepositoryTransportFile(priorPath);
+                    if (layout.stateId === priorRow.payloadVersion) {
+                        prior = {
+                            stateId: priorRow.payloadVersion,
+                            transportVersion: priorRow.transportVersion,
+                            card: layout.card,
+                            identityHash: layout.identityHash,
+                        };
+                    }
+                    else {
+                        rmSync(priorPath, { force: true });
+                    }
+                }
+                catch {
+                    // Content-addressed cache bytes are evidence, not ground. A file
+                    // that cannot prove the current envelope is a cache miss.
+                    rmSync(priorPath, { force: true });
                 }
             }
         }
-        const captured = captureRepository(repository.absolutePath, repoIdentity, prior);
+        const previousRepositories = [...existingByPath.values()]
+            .filter((row) => row.type === "repo.git");
+        const previousOwner = (row) => previousRepositories
+            .filter((candidate) => candidate.uuid !== row.uuid
+            && properDescendantOf(row.relativePath, candidate.relativePath))
+            .sort((left, right) => right.relativePath.length - left.relativePath.length)[0] ?? null;
+        const previousIdentity = prior && priorRow
+            ? [...existingByPath.values()]
+                .filter((row) => previousOwner(row)?.uuid === priorRow.uuid)
+                .map((row) => ({
+                path: priorRow.relativePath
+                    ? row.relativePath.slice(priorRow.relativePath.length + 1)
+                    : row.relativePath,
+                uuid: row.uuid,
+                type: row.type,
+                payloadVersion: row.payloadVersion,
+            }))
+                .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
+            : null;
+        const captured = captureRepository(repository.absolutePath, repoIdentity, prior, previousIdentity);
         repository.payloadVersion = captured.stateId;
         repository.transportVersion = captured.transportVersion;
-        immutableWrite(join(cacheDir, `${captured.transportVersion}.bin`), captured.bytes);
+        if (captured.bytes) {
+            immutableWrite(join(cacheDir, `${captured.transportVersion}.bin`), captured.bytes);
+        }
     }
     const children = new Map();
     for (const entry of entries) {
@@ -1103,8 +1286,7 @@ function scanRoot(input) {
             inode: entry.inode,
         };
     });
-    if (persist)
-        persistRows(database, identity, resourceId, rootUUID, rows);
+    persistRows(database, identity, resourceId, rootUUID, rows, existingRows);
     return { records: rows.map((row) => row.record), rows, referenceWorkspaceIds: [...referenceWorkspaceIds] };
 }
 function portablePaths(records) {
@@ -1204,19 +1386,10 @@ function installCloudGround(input) {
                 bindingDir: workspaceBindingDir(userRoot, identity.deviceId),
                 readContent,
             });
-            const rows = materialized.repositories.length > 0
-                ? captureMaterializedGraph({
-                    identity,
-                    resourceId: cloud.resourceId,
-                    root: roots[0],
-                    records,
-                    repositories: materialized.repositories,
-                    rootPath: userRoot,
-                    database,
-                    cacheDir,
-                    bindingDir: workspaceBindingDir(userRoot, identity.deviceId),
-                })
-                : materialized.rows;
+            const rows = projectMaterializedGraph(materialized.rows, materialized.repositories.map((repository) => ({
+                record: repository.record,
+                identity: repository.state.identity,
+            })), sha256Hex);
             persistRows(database, identity, cloud.resourceId, roots[0].uuid, rows);
         }
         catch (error) {
@@ -1237,16 +1410,32 @@ async function materializeRecords(input) {
         const artifact = artifactForRecord(record);
         if (!artifact)
             throw new Error(`cloud repository ${record.uuid} has no transfer artifact`);
-        const bytes = await readContent(artifact);
-        if (sha256Hex(bytes) !== record.transportVersion) {
+        const local = await readContent(artifact);
+        if (local.contentHash !== record.transportVersion) {
             throw new Error(`cloud repository ${record.uuid} transport is corrupt`);
         }
-        const state = unpack(bytes.toString("utf8"));
-        if (state.stateId !== record.payloadVersion) {
+        const chain = [{ file: local.file, transportVersion: local.contentHash }];
+        const versions = new Set([record.transportVersion]);
+        let state = inspectRepositoryTransportFile(local.file);
+        while (state.parentTransportVersion) {
+            if (versions.has(state.parentTransportVersion)) {
+                throw new Error(`cloud repository ${record.uuid} transport chain has a cycle`);
+            }
+            const parentVersion = state.parentTransportVersion;
+            versions.add(parentVersion);
+            const parent = await readContent({ ...artifact, contentHash: parentVersion });
+            if (parent.contentHash !== parentVersion) {
+                throw new Error(`cloud repository ${record.uuid} parent transport is corrupt`);
+            }
+            chain.unshift({ file: parent.file, transportVersion: parent.contentHash });
+            state = inspectRepositoryTransportFile(parent.file);
+        }
+        const latest = inspectRepositoryTransportFile(local.file);
+        if (latest.stateId !== record.payloadVersion) {
             throw new Error(`cloud repository ${record.uuid} transport does not name its declared state`);
         }
-        const applied = applyRepository(destination, bytes);
-        repositories.push({ record, state: applied, bytes });
+        const applied = await applyRepositoryFiles(destination, chain);
+        repositories.push({ record, state: applied });
     };
     const paths = portablePaths(records);
     const ordered = [...records].sort((left, right) => {
@@ -1295,12 +1484,12 @@ async function materializeRecords(input) {
             const artifact = artifactForRecord(record);
             if (!artifact)
                 throw new Error(`cloud leaf ${record.uuid} has no transfer artifact`);
-            const bytes = await readContent(artifact);
+            const local = await readContent(artifact);
             ensurePrivateDir(dirname(destination));
             if (record.type === "link")
-                symlinkSync(bytes.toString("utf8"), destination);
+                symlinkSync(readFileSync(local.file, "utf8"), destination);
             else
-                atomicWrite(destination, bytes);
+                atomicCopy(local.file, destination);
         }
         else {
             throw new Error(`materialization for ${record.type} requires its dedicated adapter`);
@@ -1320,50 +1509,6 @@ async function materializeRecords(input) {
     });
     return { rows, repositories };
 }
-function captureMaterializedGraph(input) {
-    const { identity, resourceId, root, records, repositories, rootPath, database, cacheDir, bindingDir, } = input;
-    if (root.type !== "workspace" && root.type !== "repo.git") {
-        throw new Error(`cloud root ${root.uuid} cannot be scanned as a workspace`);
-    }
-    const paths = portablePaths(records);
-    const seedByPath = new Map();
-    for (const record of records) {
-        const path = paths.get(record.uuid);
-        if (path)
-            seedByPath.set(path, { uuid: record.uuid, type: record.type });
-    }
-    const repositoryHeads = new Map();
-    for (const repository of repositories) {
-        if (!repository.record.transportVersion || !repository.record.payloadVersion) {
-            throw new Error(`cloud repository ${repository.record.uuid} has no transport identity`);
-        }
-        const base = paths.get(repository.record.uuid);
-        for (const entry of repository.state.identity ?? []) {
-            const path = [base, entry.path].filter(Boolean).join("/");
-            seedByPath.set(path, { uuid: entry.uuid, type: entry.type });
-        }
-        repositoryHeads.set(repository.record.uuid, {
-            stateId: repository.record.payloadVersion,
-            transportVersion: repository.record.transportVersion,
-            bytes: repository.bytes,
-        });
-    }
-    return scanRoot({
-        identity,
-        resourceId,
-        rootUUID: root.uuid,
-        rootName: root.name,
-        rootPath,
-        rootType: root.type,
-        database,
-        cacheDir,
-        policy: () => true,
-        bindingDir,
-        seedByPath,
-        repositoryHeads,
-        persist: false,
-    }).rows;
-}
 async function installCloudWorkspace(input) {
     const { identity, database, cacheDir, bindingDir, resourceId, workspace, records, destinationParent, readContent, } = input;
     const existing = readRows(database).filter((row) => row.rootUUID === workspace.uuid);
@@ -1397,19 +1542,10 @@ async function installCloudWorkspace(input) {
         const materialized = await materializeRecords({
             records, rootPath: destination, cacheDir, bindingDir, readContent,
         });
-        const rows = materialized.repositories.length > 0
-            ? captureMaterializedGraph({
-                identity,
-                resourceId,
-                root: workspace,
-                records,
-                repositories: materialized.repositories,
-                rootPath: destination,
-                database,
-                cacheDir,
-                bindingDir,
-            })
-            : materialized.rows;
+        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);
         return {
@@ -1447,7 +1583,10 @@ function readyFromFrame(frame) {
     };
 }
 function frameBytes(frame) {
-    const bytes = Buffer.from(String(frame.data_b64 || ""), "base64");
+    if (!(frame.data_bin instanceof Uint8Array)) {
+        throw new Error("wire content response is not a binary frame");
+    }
+    const bytes = Buffer.from(frame.data_bin);
     if (bytes.length !== Number(frame.bytes) || sha256Hex(bytes) !== String(frame.sha256 || "")) {
         throw new Error("wire content bytes do not match their checksum");
     }