@amalgm/shell 0.1.28 → 0.1.30

package/dist/user-ground-host.js

@@ -1,16 +1,18 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, symlinkSync, watch, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, 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 { 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, createSuspicionScope, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, download as downloadArtifact, deriveUploadManifest, membershipHash, parseSnapshot, pathIsSuspect, privateEntityResourceId, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
+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, hashContentFile } from "./content-cache-host.js";
+import { decodeContentWireBytes, encodeContentWireBytes } from "./content-wire-codec.js";
 import { WORKSPACE_UUID as UUID, createFilesRegisterPorts, pathExists, pathWithin, referenceWorkspaceId, workspaceBindingDir, } from "./files-register-host.js";
-import { applyRepositoryFiles, captureRepository, inspectRepositoryTransportFile, isRepository, } from "./git-repository-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";
+import { NodeWatchHost, } from "./watching/index.js";
 import { WireClient, WireRequestError } from "./wire-client.js";
 const PORTABLE_FIELDS = [
     "uuid", "type", "parentUUID", "name", "status", "version",
@@ -24,7 +26,7 @@ const FILE_BATCH_DOWNLOAD_CONCURRENCY = 2;
 export class UserGroundHost {
     options;
     wire;
-    watchers = new Map();
+    watchHost;
     activeIdentity = null;
     rescanTimer = null;
     watchDirty = false;
@@ -40,6 +42,11 @@ export class UserGroundHost {
             token: options.tunnelToken,
             runtimeVersion: options.runtimeVersion,
         });
+        this.watchHost = new NodeWatchHost({
+            open: options.openWatch,
+            onSignal: () => this.scheduleRescan(),
+            onHealth: options.onWatchHealth,
+        });
         this.port = {
             converge: async (identity) => {
                 this.converged = false;
@@ -72,18 +79,30 @@ export class UserGroundHost {
     rows(identity) {
         return readRows(this.databasePath(identity));
     }
-    /** Open only the authenticated Files-command effects over an already-ready
-     * local projection. This deliberately does not run login convergence or
-     * Watch registration before a cold download. */
-    openFilesCommand(identity) {
-        const normalized = normalizedIdentity(identity);
-        const database = this.databasePath(normalized);
-        if (!existsSync(database) || readRows(database).length === 0) {
-            throw new Error("Files commands require a materialized local user ground");
+    watchHealth() {
+        return this.watchHost.health();
+    }
+    watchEvidence() {
+        return this.watchHost.evidence();
+    }
+    coverWorkspaceEvidence(workspaceId) {
+        if (!this.activeIdentity || !this.converged) {
+            throw new Error("Watch coverage requires a running authenticated runtime");
         }
-        assertDatabaseIdentity(database, normalized);
-        this.activeIdentity = normalized;
-        this.converged = true;
+        const evidence = this.ensureWatchers(this.activeIdentity);
+        const watch = this.watchHost.evidence();
+        if (evidence.state !== "healthy") {
+            throw new Error(`Watch coverage is degraded: ${evidence.reason ?? "unknown failure"}`);
+        }
+        assertHealthyWatch(watch, workspaceId);
+        return watch;
+    }
+    /** Add already projects authoritative rows; this proves that the same
+     * long-lived runtime now owns their healthy ongoing coverage. */
+    addedWorkspaceEvidence(workspaceId) {
+        const watch = this.watchHost.evidence();
+        assertHealthyWatch(watch, workspaceId);
+        return watch;
     }
     /** Host effects for Live-owned Files commands. The shell CLI receives these
      * ports but never decides Files behavior itself. */
@@ -119,8 +138,8 @@ export class UserGroundHost {
                 readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact),
             }),
             coverWorkspace: async () => {
-                this.ensureWatchers(identity);
-                return { active: true, roots: this.watchers.size };
+                const health = this.ensureWatchers(identity);
+                return { active: true, roots: health.contentHandles };
             },
         };
         return { register, add };
@@ -131,8 +150,7 @@ export class UserGroundHost {
         if (!this.converged || !this.activeIdentity || !this.cloudState)
             return;
         const identity = this.activeIdentity;
-        for (const watcher of this.watchers.values())
-            watcher.suspicion.suspectAll();
+        this.watchHost.suspectAll();
         this.watchDirty = true;
         await this.syncNow();
         if (!this.closing)
@@ -155,7 +173,7 @@ export class UserGroundHost {
     async flushObservedChanges() {
         while (true) {
             const dirty = this.watchDirty
-                || [...this.watchers.values()].some((watcher) => watcher.suspicion.size > 0);
+                || this.watchHost.hasPending;
             this.watchDirty = false;
             if (dirty) {
                 await this.syncNow();
@@ -183,25 +201,20 @@ export class UserGroundHost {
             if (this.rescanTimer)
                 clearTimeout(this.rescanTimer);
             this.rescanTimer = null;
-            for (const watcher of this.watchers.values())
-                watcher.handle.close();
-            this.watchers.clear();
+            this.watchHost.close({ catchUp: false });
             await this.wire.close();
             return;
         }
         // 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.watchHost.suspectAll();
+        this.watchDirty = this.watchHost.health().logicalRoots > 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.handle.close();
-        this.watchers.clear();
+        this.watchHost.close();
         if (this.rescanTimer)
             clearTimeout(this.rescanTimer);
         this.rescanTimer = null;
@@ -284,8 +297,8 @@ export class UserGroundHost {
                 return localValue(identity, userRoot, database);
             },
             watch: async () => {
-                this.ensureWatchers(identity);
-                return { active: true, roots: this.watchers.size };
+                const health = this.ensureWatchers(identity);
+                return { active: true, roots: health.contentHandles };
             },
         };
     }
@@ -364,6 +377,7 @@ export class UserGroundHost {
                             }
                             return;
                         }
+                        const encoded = await encodeContentWireBytes(bytes);
                         await retryContent(() => this.wire.requestBinary({
                             type: "private.entity-content.put-batch",
                             resource_id: resourceId,
@@ -376,7 +390,9 @@ export class UserGroundHost {
                                 bytes: manifest.chunks[index]?.bytes,
                             })),
                             bytes: bytes.byteLength,
-                        }, bytes, ["private.entity-content.stored-batch"]));
+                            wire_bytes: encoded.bytes.byteLength,
+                            ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
+                        }, encoded.bytes, ["private.entity-content.stored-batch"]));
                     },
                     putManifest: async (_candidate, manifest) => {
                         if (manifestPresent)
@@ -466,7 +482,7 @@ export class UserGroundHost {
                             bytes: manifest.chunks[index]?.bytes,
                         })),
                     }, ["private.entity-content.data-batch"]), true);
-                    return binaryFrameBytes(frame);
+                    return decodeContentWireBytes(binaryWireFrameBytes(frame), frame.content_encoding, Number(frame.bytes));
                 },
                 putChunk: async (_candidate, _manifest, index, bytes) => {
                     if (!cache.target)
@@ -493,64 +509,57 @@ export class UserGroundHost {
     }
     ensureWatchers(identity) {
         if (this.closing)
-            return;
+            return this.watchHost.health();
         const root = this.userRoot(identity);
-        const ignoreFile = join(root, ".amalgmignore");
-        const policy = createUserGroundEnrollmentPolicy(existsSync(ignoreFile) ? readFileSync(ignoreFile, "utf8") : "");
-        const wanted = new Map([[root, policy]]);
+        const wanted = new Map([[root, {
+                    rootId: `user:${identity.userId}`,
+                    directory: root,
+                    materialized: directoryExists(root),
+                    excludedSubtrees: [join(root, ".amalgm")],
+                }]]);
+        const bindings = workspaceBindingDir(root, identity.deviceId);
+        if (existsSync(bindings)) {
+            for (const entry of readdirSync(bindings, { withFileTypes: true })) {
+                if (!entry.isSymbolicLink() || !UUID.test(entry.name))
+                    continue;
+                const binding = join(bindings, entry.name);
+                try {
+                    const directory = realpathSync(binding);
+                    if (!directoryExists(directory))
+                        continue;
+                    wanted.set(directory, {
+                        rootId: entry.name.toLowerCase(),
+                        directory,
+                        materialized: true,
+                    });
+                }
+                catch {
+                    // A missing external target has no trustworthy address until Detect
+                    // rescues or rebinds it; its prior entity row remains below.
+                }
+            }
+        }
         for (const row of readRows(this.databasePath(identity))) {
             if (row.parentUUID !== null || row.absolutePath === root)
                 continue;
-            try {
-                if (statSync(row.absolutePath).isDirectory())
-                    wanted.set(row.absolutePath, () => true);
-            }
-            catch {
-                // Unresolved ground keeps its rows but cannot hold a watcher handle.
-            }
-        }
-        for (const [directory, watcher] of this.watchers) {
-            if (!wanted.has(directory)) {
-                watcher.handle.close();
-                this.watchers.delete(directory);
+            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}`);
             }
-        }
-        for (const [directory, enrollment] of wanted) {
-            if (this.watchers.has(directory))
-                continue;
-            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();
-            });
-            handle.on("error", () => {
-                suspicion.suspectAll();
-                handle.close();
-                this.watchers.delete(directory);
-                this.scheduleRescan();
+            wanted.set(directory, {
+                rootId: row.rootUUID,
+                directory,
+                materialized: directoryExists(directory),
             });
-            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();
         }
+        const health = this.watchHost.reconcile([...wanted.values()]);
+        if (health.state !== "healthy" || health.contentHandles < 1) {
+            throw new Error(`Watch coverage is degraded: ${health.reason ?? "no content coverage"}`);
+        }
+        return health;
     }
     scheduleRescan() {
         if (this.closing)
@@ -577,23 +586,18 @@ 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 observations = this.watchHost.observations();
         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])),
+            suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion.paths])),
         });
         const snapshot = snapshotFromRecords(travelingRecords(mergeMaterializedRoots(state.records, localRecords)));
         const checksum = sha256Hex(stableJson(snapshot));
         if (checksum === state.checksum) {
-            for (const [directory, snapshot] of observations) {
-                this.watchers.get(directory)?.suspicion.settle(snapshot);
-            }
+            this.watchHost.settle(observations);
             return;
         }
         const database = initializeDatabase(this.databasePath(identity));
@@ -609,9 +613,7 @@ export class UserGroundHost {
             database.close();
         }
         await this.drainOutbox(identity);
-        for (const [directory, snapshot] of observations) {
-            this.watchers.get(directory)?.suspicion.settle(snapshot);
-        }
+        this.watchHost.settle(observations);
     }
     async drainOutboxBeforeLookup(identity, resourceId) {
         const pending = readOutbox(this.databasePath(identity));
@@ -682,6 +684,23 @@ function normalizedIdentity(identity) {
         deviceId: String(identity.deviceId).trim(),
     };
 }
+function assertHealthyWatch(evidence, rootId) {
+    const root = evidence.roots.find((candidate) => candidate.rootId === rootId);
+    const content = root?.contentOwner
+        ? evidence.content.find((candidate) => candidate.directory === root.contentOwner)
+        : undefined;
+    const address = root?.contentOwner
+        ? evidence.addresses.find((candidate) => candidate.rootIds.includes(rootId))
+        : undefined;
+    if (evidence.health.state !== "healthy"
+        || evidence.health.contentHandles !== evidence.content.length
+        || evidence.health.addressHandles !== evidence.addresses.length
+        || !root?.materialized
+        || !content?.rootIds.includes(rootId)
+        || !address) {
+        throw new Error(`Watch coverage is not healthy for workspace ${rootId}: ${evidence.health.reason ?? "incomplete handle evidence"}`);
+    }
+}
 function immutableWrite(file, bytes) {
     ensurePrivateDir(dirname(file));
     try {
@@ -925,6 +944,14 @@ function fileType(bytes) {
 function slashPath(path) {
     return path.split(sep).join("/");
 }
+function directoryExists(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function scanAndRegister(input) {
     const { identity, userRoot, database, cacheDir, suspicions } = input;
     const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
@@ -980,7 +1007,7 @@ function scanAndRegister(input) {
             rootUUID: workspaceId,
             rootName: existingRoot?.name || basename(rootPath),
             rootPath,
-            rootType: classifyRegisteredRoot({ repository: isRepository(rootPath) }),
+            rootType: classifyRegisteredRoot({ repository: hasGitMarker(rootPath) }),
             database,
             cacheDir,
             policy: () => true,
@@ -1070,7 +1097,15 @@ function scanRoot(input) {
                 ? slashPath(relative(activeRepository.root, absolutePath))
                 : null;
             if (observe && repositoryPath && activeRepository && !activeRepository.evidence) {
-                activeRepository.evidence = inspectGitRegistration(activeRepository.root, activeRepository.evidencePaths);
+                try {
+                    activeRepository.evidence = inspectGitRegistration(activeRepository.root, activeRepository.evidencePaths);
+                }
+                catch {
+                    // Classification already settled from the marker. If Git cannot
+                    // provide clean-index evidence, read current worktree bytes; Card +
+                    // Checkpoint capture below remains the transfer retry boundary.
+                    activeRepository.evidence = { cleanLeaves: new Map() };
+                }
             }
             const indexed = observe && repositoryPath
                 ? activeRepository?.evidence?.cleanLeaves.get(repositoryPath)
@@ -1110,7 +1145,7 @@ function scanRoot(input) {
                 }
             }
             else if (stats.isDirectory()) {
-                type = classifyDirectory({ repository: isRepository(absolutePath) });
+                type = classifyDirectory({ repository: hasGitMarker(absolutePath) });
             }
             else if (stats.isFile()) {
                 if (indexed && indexed.type !== "link") {
@@ -1157,81 +1192,6 @@ function scanRoot(input) {
         }
     };
     visit(rootPath, rootUUID, rootType);
-    const repositories = entries.filter((entry) => entry.type === "repo.git");
-    const properDescendantOf = (candidate, ancestor) => ancestor === "" ? candidate !== "" : candidate.startsWith(`${ancestor}/`);
-    const repositoryOwner = (entry) => repositories
-        .filter((repository) => repository.uuid !== entry.uuid
-        && properDescendantOf(entry.relativePath, repository.relativePath))
-        .sort((left, right) => right.relativePath.length - left.relativePath.length)[0] ?? null;
-    for (const repository of repositories) {
-        const repoIdentity = entries
-            .filter((entry) => repositoryOwner(entry)?.uuid === repository.uuid)
-            .map((entry) => ({
-            path: repository.relativePath
-                ? entry.relativePath.slice(repository.relativePath.length + 1)
-                : 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 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)) {
-                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 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;
-        if (captured.bytes) {
-            immutableWriteArtifact(cacheDir, {
-                entityId: repository.uuid,
-                entityType: "repo.git",
-                kind: "git",
-                contentHash: captured.transportVersion,
-            }, captured.bytes);
-        }
-    }
     const children = new Map();
     for (const entry of entries) {
         if (entry.parentUUID === null)
@@ -1240,7 +1200,7 @@ function scanRoot(input) {
         group.push({ uuid: entry.uuid, name: entry.name });
         children.set(entry.parentUUID, group);
     }
-    const rows = entries.map((entry) => {
+    const rowsFromEntries = () => entries.map((entry) => {
         const versionPayload = entry.type === "workspace" || entry.type === "folder"
             ? membershipHash(children.get(entry.uuid) ?? [], sha256Hex)
             : entry.payloadVersion;
@@ -1268,7 +1228,100 @@ function scanRoot(input) {
             inode: entry.inode,
         };
     });
-    persistRows(database, identity, resourceId, rootUUID, rows, existingRows);
+    const persistCurrentRows = () => {
+        const rows = rowsFromEntries();
+        persistRows(database, identity, resourceId, rootUUID, rows, existingRows);
+        return rows;
+    };
+    const repositories = entries.filter((entry) => entry.type === "repo.git");
+    const properDescendantOf = (candidate, ancestor) => ancestor === "" ? candidate !== "" : candidate.startsWith(`${ancestor}/`);
+    const repositoryOwner = (entry) => repositories
+        .filter((repository) => repository.uuid !== entry.uuid
+        && properDescendantOf(entry.relativePath, repository.relativePath))
+        .sort((left, right) => right.relativePath.length - left.relativePath.length)[0] ?? null;
+    try {
+        for (const repository of repositories) {
+            const repoIdentity = entries
+                .filter((entry) => repositoryOwner(entry)?.uuid === repository.uuid)
+                .map((entry) => ({
+                path: repository.relativePath
+                    ? entry.relativePath.slice(repository.relativePath.length + 1)
+                    : 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 priorRow = existingByPath.get(repository.relativePath);
+            if (priorRow?.type === "repo.git") {
+                repository.payloadVersion = priorRow.payloadVersion;
+                repository.transportVersion = priorRow.transportVersion;
+            }
+            let prior = null;
+            if (priorRow?.type === "repo.git" && priorRow.payloadVersion && priorRow.transportVersion) {
+                const priorPath = join(cacheDir, `${priorRow.transportVersion}.bin`);
+                if (existsSync(priorPath)) {
+                    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 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;
+            if (captured.bytes) {
+                immutableWriteArtifact(cacheDir, {
+                    entityId: repository.uuid,
+                    entityType: "repo.git",
+                    kind: "git",
+                    contentHash: captured.transportVersion,
+                }, captured.bytes);
+            }
+        }
+    }
+    catch (error) {
+        // Type and identity are filesystem facts, so they settle locally even
+        // when the selected repository rail cannot yet capture its artifact.
+        // Cloud publication remains commit-last because this failure propagates.
+        persistCurrentRows();
+        throw error;
+    }
+    const rows = persistCurrentRows();
     return { records: rows.map((row) => row.record), rows, referenceWorkspaceIds: [...referenceWorkspaceIds] };
 }
 function portablePaths(records) {
@@ -1582,13 +1635,20 @@ function readyFromFrame(frame) {
  * against their manifest, so the host must not copy or hash those bytes a
  * second time before returning them to the portable operation. */
 function binaryFrameBytes(frame) {
+    const bytes = binaryWireFrameBytes(frame);
+    if (frame.content_encoding !== undefined || bytes.length !== Number(frame.bytes)) {
+        throw new Error("wire content byte count does not match its header");
+    }
+    return bytes;
+}
+function binaryWireFrameBytes(frame) {
     if (!(frame.data_bin instanceof Uint8Array)) {
         throw new Error("wire content response is not a binary frame");
     }
     const bytes = Buffer.isBuffer(frame.data_bin)
         ? frame.data_bin
         : Buffer.from(frame.data_bin.buffer, frame.data_bin.byteOffset, frame.data_bin.byteLength);
-    if (bytes.length !== Number(frame.bytes)) {
+    if (bytes.length !== Number(frame.wire_bytes ?? frame.bytes)) {
         throw new Error("wire content byte count does not match its header");
     }
     return bytes;