@amalgm/shell 0.1.108 → 0.1.110

package/dist/user-ground-host.js

@@ -1,9 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, } from "node:fs";
-import { open } from "node:fs/promises";
+import { open, readFile } 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, CONTENT_CONTRACT, INLINE_CARGO_MAX_BYTES, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, decodeAcceptedEntityRecord, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, downloadAll as downloadAllArtifacts, encodeEntityRecord, EntityApplyRail, EntityRecordRail, membershipHash, parseSnapshot, pathIsSuspect, PRESIGN_BATCH_OBJECTS, privateEntityResourceId, repositoryIdentityHash, rootReplacementFromRecords, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
+import { CHUNK_BYTES, CONTENT_CONTRACT, INLINE_CARGO_MAX_BYTES, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, decodeAcceptedEntityRecord, deriveUploadManifest, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, downloadAll as downloadAllArtifacts, encodeEntityRecord, EntityApplyRail, EntityRecordRail, membershipHash, parseSnapshot, pathIsSuspect, planCargoWaves, PRESIGN_BATCH_OBJECTS, privateEntityResourceId, repositoryIdentityHash, rootReplacementFromRecords, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
 import Database from "better-sqlite3";
 import { atomicCopy, atomicWrite, ensurePrivateDir, ensureUserDir } from "./filesystem.js";
 import { emitFilesStage, } from "./files-observability.js";
@@ -27,7 +27,9 @@ import { GroundCoordinator } from "./ground-coordination.js";
 import { submitMutationOperation } from "./paged-mutation-submit.js";
 import { adoptSnapshotDeliveryBaseline } from "./snapshot-delivery-baseline.js";
 import { WireClient, WireRequestError } from "./wire-client.js";
-const SMALL_CONTENT_UPLOAD_CONCURRENCY = 16;
+/** Cargo waves hold up to 16MiB of payload each; two in flight bounds the
+ * upload path's memory while keeping the wire busy. */
+const CARGO_UPLOAD_CONCURRENCY = 2;
 /** Storage-object lanes for one download set. Tiny objects use the wide
  * request window, while the separate byte budget narrows large chunks so
  * request concurrency can never silently become an unbounded memory claim. */
@@ -44,6 +46,13 @@ const DETECT_RETRY_MS = 250;
 /** A Detect walk yields the event loop this often so Send, Receive, and
  * Apply progress during a large reconciliation instead of queueing behind it. */
 const DETECT_WALK_YIELD_ENTRIES = 256;
+/** File captures during a walk overlap reads and hashing across this many
+ * lanes; the directory traversal itself stays ordered and serial. */
+const WALK_CAPTURE_CONCURRENCY = 8;
+/** How many times one register attempt re-derives after ground moved under
+ * its capture. Each attempt re-walks at read+hash speed, so steady churn is
+ * surfaced instead of chased forever. */
+const REGISTER_STALE_CAPTURE_ATTEMPTS = 3;
 const DOWNLOAD_CONTENT_RETRY_ATTEMPTS = 3;
 const APPLY_GROUND_WAIT_TIMEOUT_MS = 15_000;
 const GROUND_ROW_COLUMNS = [
@@ -529,19 +538,30 @@ export class UserGroundHost {
             // unchanged while a contract cutover moved its cargo namespace, so
             // the publish path re-proves seal evidence and repairs any missing
             // uploads before this answer is lawful.
+            let staleRepair = false;
             try {
                 const deliveryWatermark = await this.prepareSnapshotPublication(identity, { journey: "register", workspaceId });
                 await this.publishMaterializedSnapshot(identity, new Set([workspaceId]), deliveryWatermark, { journey: "register", workspaceId });
             }
-            finally {
+            catch (error) {
+                // A stale capture means a repair upload's evidence no longer matches
+                // the ground it was captured from. The full walk below recaptures
+                // and republishes current truth instead of failing the register.
+                if (!staleCapture(error)) {
+                    this.finishColdOperation();
+                    throw error;
+                }
+                staleRepair = true;
+            }
+            if (!staleRepair) {
                 this.finishColdOperation();
+                return {
+                    registered: true,
+                    entityCount: countDescendantRows(database, workspaceId),
+                    cloudHead: this.cloudState.checksum,
+                    watch,
+                };
             }
-            return {
-                registered: true,
-                entityCount: countDescendantRows(database, workspaceId),
-                cloudHead: this.cloudState.checksum,
-                watch,
-            };
         }
         // Register is a cold declaration, not a filesystem edit. It performs one
         // complete reconciliation and publishes one graph head; it must not mint
@@ -575,75 +595,88 @@ export class UserGroundHost {
             const observations = this.watchHost.observations().filter((observation) => observation.directory === this.userRoot(identity)
                 || pathWithin(contentOwner, observation.directory));
             this.watchDirty = false;
-            const registrationStarted = performance.now();
-            this.stage({
-                primitive: "register", stage: "entity-registration", status: "started", workspaceId,
-            });
-            const scanned = await reconcileGround({
-                identity,
-                userRoot: this.userRoot(identity),
-                database: this.databasePath(identity),
-                cacheDir: this.cacheDir(identity),
-                onScan: (evidence) => this.reportDetectScan(evidence),
-                registrationWorkspaceId: workspaceId,
-                suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion])),
-            });
-            const retry = scanned.detection.find((plan) => plan.kind === "retry");
-            if (retry?.kind === "retry") {
-                throw new Error(retry.reasons.join("; "));
-            }
-            const registrationDuration = performance.now() - registrationStarted;
-            const commitStarted = performance.now();
-            this.stage({
-                primitive: "register", stage: "entity-sqlite-commit", status: "started", workspaceId,
-            });
-            const committed = commitDetectedState(this.databasePath(identity), {
-                notebookBasis: scanned.notebookBasis,
-                acceptedMaterializedRows: scanned.acceptedMaterializedRows,
-                materializedRemovals: scanned.materializedRemovals,
-                acceptedNotebookRows: scanned.acceptedNotebookRows,
-                notebookRemovals: scanned.notebookRemovals,
-            });
-            if (!committed) {
-                throw new Error("verified ground advanced while registration was observing; retry");
-            }
-            this.stage({
-                primitive: "register",
-                stage: "entity-sqlite-commit",
-                status: "completed",
-                workspaceId,
-                durationMs: performance.now() - commitStarted,
-            });
-            if (scanned.transferFailures.length > 0) {
-                const details = scanned.transferFailures
-                    .map(({ rootId, reason }) => `${rootId}: ${reason}`)
-                    .join("; ");
-                this.stage({
-                    primitive: "register",
-                    stage: "entity-registration",
-                    status: "failed",
-                    workspaceId,
-                    durationMs: registrationDuration,
-                    measurements: { roots: scanned.transferFailures.length },
-                });
-                throw pipelineStageError("entity registration", new Error(`repository state could not be captured: ${details}`));
-            }
-            this.stage({
-                primitive: "register",
-                stage: "entity-registration",
-                status: "completed",
-                workspaceId,
-                durationMs: registrationDuration,
-                measurements: {
-                    roots: scanned.publicationRootIds?.length ?? 0,
-                    rows: scanned.acceptedMaterializedRows.length,
-                },
-            });
-            this.namedDetect?.refreshEnrollmentPolicy();
-            if (!scanned.publicationRootIds) {
-                throw new Error("cold registration reconciliation did not name its publication roots");
+            // Ground may move between a walk's capture and its upload. Each retry
+            // re-walks and republishes the ground as it now is — bounded, because
+            // a workspace under continuous mutation belongs to Watch afterwards,
+            // not to an endless register.
+            for (let attempt = 1;; attempt++) {
+                try {
+                    const registrationStarted = performance.now();
+                    this.stage({
+                        primitive: "register", stage: "entity-registration", status: "started", workspaceId,
+                    });
+                    const scanned = await reconcileGround({
+                        identity,
+                        userRoot: this.userRoot(identity),
+                        database: this.databasePath(identity),
+                        cacheDir: this.cacheDir(identity),
+                        onScan: (evidence) => this.reportDetectScan(evidence),
+                        registrationWorkspaceId: workspaceId,
+                        suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion])),
+                    });
+                    const retry = scanned.detection.find((plan) => plan.kind === "retry");
+                    if (retry?.kind === "retry") {
+                        throw new Error(retry.reasons.join("; "));
+                    }
+                    const registrationDuration = performance.now() - registrationStarted;
+                    const commitStarted = performance.now();
+                    this.stage({
+                        primitive: "register", stage: "entity-sqlite-commit", status: "started", workspaceId,
+                    });
+                    const committed = commitDetectedState(this.databasePath(identity), {
+                        notebookBasis: scanned.notebookBasis,
+                        acceptedMaterializedRows: scanned.acceptedMaterializedRows,
+                        materializedRemovals: scanned.materializedRemovals,
+                        acceptedNotebookRows: scanned.acceptedNotebookRows,
+                        notebookRemovals: scanned.notebookRemovals,
+                    });
+                    if (!committed) {
+                        throw new Error("verified ground advanced while registration was observing; retry");
+                    }
+                    this.stage({
+                        primitive: "register",
+                        stage: "entity-sqlite-commit",
+                        status: "completed",
+                        workspaceId,
+                        durationMs: performance.now() - commitStarted,
+                    });
+                    if (scanned.transferFailures.length > 0) {
+                        const details = scanned.transferFailures
+                            .map(({ rootId, reason }) => `${rootId}: ${reason}`)
+                            .join("; ");
+                        this.stage({
+                            primitive: "register",
+                            stage: "entity-registration",
+                            status: "failed",
+                            workspaceId,
+                            durationMs: registrationDuration,
+                            measurements: { roots: scanned.transferFailures.length },
+                        });
+                        throw pipelineStageError("entity registration", new Error(`repository state could not be captured: ${details}`));
+                    }
+                    this.stage({
+                        primitive: "register",
+                        stage: "entity-registration",
+                        status: "completed",
+                        workspaceId,
+                        durationMs: registrationDuration,
+                        measurements: {
+                            roots: scanned.publicationRootIds?.length ?? 0,
+                            rows: scanned.acceptedMaterializedRows.length,
+                        },
+                    });
+                    this.namedDetect?.refreshEnrollmentPolicy();
+                    if (!scanned.publicationRootIds) {
+                        throw new Error("cold registration reconciliation did not name its publication roots");
+                    }
+                    await this.publishMaterializedSnapshot(identity, new Set(scanned.publicationRootIds), deliveryWatermark, { journey: "register", workspaceId }, scanned.largeManifests);
+                    break;
+                }
+                catch (error) {
+                    if (!staleCapture(error) || attempt >= REGISTER_STALE_CAPTURE_ATTEMPTS)
+                        throw error;
+                }
             }
-            await this.publishMaterializedSnapshot(identity, new Set(scanned.publicationRootIds), deliveryWatermark, { journey: "register", workspaceId });
             this.watchHost.settle(observations);
         }
         catch (error) {
@@ -762,10 +795,9 @@ export class UserGroundHost {
             throw new Error("entity Record rail already started");
         await this.wire.open();
         // One floor, no per-feature gates: this shell and its gateway release
-        // together, and the gateway ships first. 11 = snapshot delivery
-        // watermarks; an older gateway cannot atomically bind Add's graph to the
-        // official entity-record prefix it already includes.
-        if (this.wire.protocolVersion < 11) {
+        // together, and the gateway ships first. 12 = bounded cold-Register cargo
+        // waves; an older gateway cannot verify and seal that upload frame.
+        if (this.wire.protocolVersion < 12) {
             throw new Error("gateway speaks an older wire protocol than this shell");
         }
         this.adoptCloudDeliveryBaseline(identity, this.cloudState.deliveryWatermark);
@@ -1152,27 +1184,15 @@ export class UserGroundHost {
         }
         return inline;
     }
-    async uploadSnapshotContent(identity, resourceId, records, trace) {
+    async uploadSnapshotContent(identity, resourceId, records, trace, manifestHints) {
         const cache = this.cacheDir(identity);
         const byHash = new Map();
         for (const record of records) {
             const artifact = artifactForRecord(record);
-            if (artifact)
-                byHash.set(artifact.contentHash, artifact);
+            if (artifact && !byHash.has(artifact.contentHash)) {
+                byHash.set(artifact.contentHash, { artifact, uuid: record.uuid });
+            }
         }
-        const sources = [...byHash.values()].map((artifact) => {
-            const file = contentCacheFile(cache, artifact.contentHash);
-            const manifest = readCachedManifest(cache, artifact.contentHash);
-            return {
-                artifact,
-                file,
-                manifest,
-                // A retained manifest can prove the remote inventory without local
-                // cargo bytes. The source file is required only when the authority
-                // reports a missing block.
-                bytes: manifest?.bytes ?? statSync(file).size,
-            };
-        });
         const started = performance.now();
         let uploadedChunks = 0;
         let reusedChunks = 0;
@@ -1190,14 +1210,121 @@ export class UserGroundHost {
             ...identifiers,
             measurements: {
                 journey: trace?.journey ?? "bootstrap",
-                artifacts: sources.length,
-                declaredBytes: sources.reduce((total, source) => total + source.bytes, 0),
+                artifacts: byHash.size,
             },
         });
+        // The authority's seal inventory is the only permission to skip an
+        // upload — asked before any source is touched, so sealed artifacts cost
+        // zero local reads and a retried publication whose upload already sealed
+        // completely never needs its captured ground to still exist.
+        const alreadySealed = await this.sealedContentHashes(resourceId, [...byHash.keys()]);
+        const unsealed = [...byHash.values()]
+            .filter(({ artifact }) => !alreadySealed.has(artifact.contentHash));
+        const rows = readGroundRowsByUuid(this.databasePath(identity), unsealed.map(({ uuid }) => uuid));
+        // Each artifact uploads from the strongest evidence available: a cache
+        // copy when another journey pinned one, otherwise the ground entity
+        // itself. Register stages nothing, so the ground path is the common
+        // case — and every read is re-proven against the captured hash, turning
+        // ground churn into a stale capture instead of a wrong upload.
+        const sources = unsealed.map(({ artifact, uuid }) => {
+            const cached = contentCacheFile(cache, artifact.contentHash);
+            const fromCache = existsSync(cached);
+            const row = rows.get(uuid);
+            if (!fromCache && artifact.kind === "git") {
+                // Ground holds the working tree, never the transport parcel; a
+                // lost parcel means recapturing the repository as it now is.
+                throw new StaleCaptureError(`repository parcel ${artifact.contentHash} is no longer captured`);
+            }
+            if (!fromCache && !row) {
+                throw new StaleCaptureError(`entity ${uuid} left the ground before uploading ${artifact.contentHash}`);
+            }
+            const file = fromCache ? cached : row.absolutePath;
+            let linkTarget;
+            let bytes;
+            try {
+                if (!fromCache && artifact.kind === "link") {
+                    linkTarget = Buffer.from(readlinkSync(file), "utf8");
+                    bytes = linkTarget.byteLength;
+                }
+                else {
+                    bytes = statSync(file).size;
+                }
+            }
+            catch (error) {
+                throw new StaleCaptureError(`source for ${artifact.contentHash} is no longer readable`, { cause: error });
+            }
+            const declared = manifestHints?.get(artifact.contentHash)
+                ?? readCachedManifest(cache, artifact.contentHash)
+                ?? undefined;
+            return {
+                artifact,
+                file,
+                fromCache,
+                ...(linkTarget ? { linkTarget } : {}),
+                // Retained evidence only counts while it still describes the exact
+                // source being read; a disagreeing manifest is re-derived instead.
+                ...(declared && declared.bytes === bytes ? { manifest: declared } : {}),
+                bytes,
+            };
+        });
+        const stale = (source, error) => {
+            if (source.fromCache) {
+                // A cache copy that no longer proves its hash is torn evidence:
+                // purge it so the retry reads the ground itself.
+                rmSync(source.file, { force: true });
+                rmSync(manifestCacheFile(cache, source.artifact.contentHash), { force: true });
+            }
+            throw new StaleCaptureError(`${source.artifact.contentHash} no longer matches its source`, { cause: error });
+        };
+        // Complete small artifacts ride cargo waves: whole artifacts per frame,
+        // verified and sealed by the authority in the same round trip, so the
+        // frame count scales with bytes moved, never with file count. Large
+        // artifacts keep per-artifact transfer where chunk reuse pays.
         const small = sources.filter((source) => source.bytes <= CHUNK_BYTES);
         const large = sources.filter((source) => source.bytes > CHUNK_BYTES);
+        let cargoWaves = 0;
+        const transferCargoWave = async (wave) => {
+            const loaded = await Promise.all(wave.items.map(async (source) => {
+                try {
+                    const bytes = source.linkTarget ?? await readFile(source.file);
+                    return {
+                        source,
+                        bytes,
+                        manifest: deriveUploadManifest(source.artifact, bytes, sha256Hex),
+                    };
+                }
+                catch (error) {
+                    if (sourceMismatch(error))
+                        stale(source, error);
+                    throw error;
+                }
+            }));
+            const payload = Buffer.concat(loaded.map((item) => item.bytes));
+            const encoded = await encodeContentWireBytes(payload);
+            const frame = await retryContent(() => this.wire.requestBinary({
+                type: "private.entity-content.put-cargo",
+                resource_id: resourceId,
+                artifacts: loaded.map((item) => ({
+                    content_hash: item.source.artifact.contentHash,
+                    bytes: item.manifest.bytes,
+                    chunks: item.manifest.chunks.map((chunk) => ({ sha256: chunk.sha256, bytes: chunk.bytes })),
+                })),
+                bytes: payload.byteLength,
+                wire_bytes: encoded.bytes.byteLength,
+                ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
+            }, encoded.bytes, ["private.entity-content.stored-cargo"]));
+            const sealed = new Set(Array.isArray(frame.sealed) ? frame.sealed.map(String) : []);
+            for (const item of loaded) {
+                if (!sealed.has(item.source.artifact.contentHash)) {
+                    throw new Error(`content authority did not seal ${item.source.artifact.contentHash}`);
+                }
+                uploadedChunks += item.manifest.chunks.length;
+            }
+            uploadedBytes += encoded.bytes.byteLength;
+            cargoWaves += 1;
+        };
         const transfer = async (source) => {
-            const { artifact, file, manifest: cachedManifest, bytes: fileBytes } = source;
+            const { artifact, file, manifest: knownManifest, bytes: fileBytes } = source;
             const sourceFile = { handle: null };
             let manifestPresent = false;
             const putChunk = async (manifest, index, bytes) => {
@@ -1219,8 +1346,7 @@ export class UserGroundHost {
             try {
                 const receipt = await uploadArtifact(artifact, {
                     bytes: fileBytes,
-                    ...(cachedManifest ? { manifest: cachedManifest } : {}),
-                    ...(cachedManifest ? { manifestVerified: true } : {}),
+                    ...(knownManifest ? { manifest: knownManifest, manifestVerified: true } : {}),
                     verify: async (contentHash) => await hashContentFile(file) === contentHash,
                     read: async (offset, bytes) => {
                         sourceFile.handle ??= open(file, "r");
@@ -1283,7 +1409,11 @@ export class UserGroundHost {
                 });
                 uploadedChunks += receipt.uploadedChunks;
                 reusedChunks += receipt.reusedChunks;
-                atomicWrite(manifestCacheFile(cache, artifact.contentHash), stableJson(receipt.manifest));
+            }
+            catch (error) {
+                if (sourceMismatch(error))
+                    stale(source, error);
+                throw error;
             }
             finally {
                 if (sourceFile.handle)
@@ -1291,7 +1421,7 @@ export class UserGroundHost {
             }
         };
         try {
-            await boundedForEach(small, SMALL_CONTENT_UPLOAD_CONCURRENCY, transfer);
+            await boundedForEach([...planCargoWaves(small)], CARGO_UPLOAD_CONCURRENCY, transferCargoWave);
             for (const source of large) {
                 await transfer(source);
             }
@@ -1303,12 +1433,14 @@ export class UserGroundHost {
                 durationMs: performance.now() - started,
                 measurements: {
                     journey: trace?.journey ?? "bootstrap",
-                    artifacts: sources.length,
+                    artifacts: byHash.size,
+                    reusedArtifacts: byHash.size - sources.length,
                     declaredBytes: sources.reduce((total, source) => total + source.bytes, 0),
                     uploadedBytes,
                     uploadedChunks,
                     reusedChunks,
                     inventoryRequests,
+                    cargoWaves,
                 },
             });
         }
@@ -1815,9 +1947,11 @@ export class UserGroundHost {
         catch (error) {
             // A conclusive refusal settles the intent as rejected: the lookup that
             // follows fetches authoritative state and a later register supersedes
-            // the settled row, so a refused publication never wedges startup. An
+            // the settled row, so a refused publication never wedges startup. A
+            // stale capture already deleted its unsubmitted row — the intent will
+            // be re-derived from current ground by the next register boundary. An
             // unknown outcome must keep blocking — the mutation may have landed.
-            if (!conclusivelyRefused(error))
+            if (!conclusivelyRefused(error) && !staleCapture(error))
                 throw error;
             this.cloudState = null;
         }
@@ -1828,12 +1962,13 @@ export class UserGroundHost {
     async prepareSnapshotPublication(identity, trace) {
         // An older durable publication resolves before the new boundary derives.
         // Unknown outcomes remain pending; a conclusive refusal may be replaced
-        // by the newer complete snapshot below.
+        // by the newer complete snapshot below; a stale capture already deleted
+        // its unsubmitted row and the boundary being prepared re-derives it.
         try {
             await this.publishPendingSnapshots(identity, trace);
         }
         catch (error) {
-            if (!conclusivelyRefused(error))
+            if (!conclusivelyRefused(error) && !staleCapture(error))
                 throw error;
         }
         await this.recordRail?.flush();
@@ -1851,7 +1986,7 @@ export class UserGroundHost {
         await this.applyRail?.flush();
         return deliveryWatermark;
     }
-    async publishMaterializedSnapshot(identity, publicationRootIds, deliveryWatermark, trace) {
+    async publishMaterializedSnapshot(identity, publicationRootIds, deliveryWatermark, trace, manifestHints) {
         const state = this.cloudState;
         if (!state)
             throw new Error("cloud state is unavailable for graph publication");
@@ -1893,7 +2028,7 @@ export class UserGroundHost {
             // repair on the next Register.
             if (uploadRecords.length > 0) {
                 try {
-                    await this.uploadSnapshotContent(identity, state.resourceId, uploadRecords, trace);
+                    await this.uploadSnapshotContent(identity, state.resourceId, uploadRecords, trace, manifestHints);
                 }
                 catch (error) {
                     throw pipelineStageError("cloud upload", error);
@@ -1924,7 +2059,7 @@ export class UserGroundHost {
             replacementRecords: replacement.records,
             status: "pending",
         });
-        await this.publishPendingSnapshots(identity, trace);
+        await this.publishPendingSnapshots(identity, trace, manifestHints);
     }
     /** Which of these heads does the authority hold sealed under the current
      * content contract? Batched so a whole workspace costs a handful of
@@ -1949,7 +2084,7 @@ export class UserGroundHost {
         }
         return sealed;
     }
-    async publishPendingSnapshots(identity, trace) {
+    async publishPendingSnapshots(identity, trace, manifestHints) {
         for (const pending of readSnapshotPublications(this.databasePath(identity))) {
             // A rejected row is a settled fact, not an intent: the authority
             // conclusively refused this exact mutation, and only a newer complete
@@ -1959,9 +2094,17 @@ export class UserGroundHost {
             const snapshot = snapshotFromRecords(JSON.parse(pending.snapshotJson).records || []);
             const replacement = rootReplacementFromRecords(pending.replacementRootIds, pending.replacementRecords);
             try {
-                await this.uploadSnapshotContent(identity, pending.resourceId, pending.uploadRecords, trace);
+                await this.uploadSnapshotContent(identity, pending.resourceId, pending.uploadRecords, trace, manifestHints);
             }
             catch (error) {
+                // An unsubmitted pending row is a local intent the authority has
+                // never seen. When its captured ground moved before upload, the
+                // intent is simply stale: delete it and let the caller re-derive
+                // one from current ground. A submitted row never lands here — its
+                // upload sealed completely before the first submit frame left.
+                if (staleCapture(error) && !pending.submitted) {
+                    deleteJournalEntry(this.databasePath(identity), pending.mutationId);
+                }
                 throw pipelineStageError("cloud upload", error);
             }
             let frame;
@@ -1975,6 +2118,9 @@ export class UserGroundHost {
                     ...(trace.mutationId ? { mutationId: trace.mutationId } : {}),
                 });
             }
+            if (!pending.submitted) {
+                markSnapshotJournalSubmitted(this.databasePath(identity), pending.mutationId);
+            }
             try {
                 frame = await submitMutationOperation(this.wire, {
                     resourceId: pending.resourceId,
@@ -2221,7 +2367,8 @@ function initializeDatabase(file) {
       resource_id TEXT NOT NULL,
       publication_json TEXT NOT NULL,
       created_at INTEGER NOT NULL,
-      status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'rejected'))
+      status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'rejected')),
+      submitted_at INTEGER
     );
     CREATE TABLE IF NOT EXISTS workspace_add_intents (
       workspace_uuid TEXT PRIMARY KEY,
@@ -2262,6 +2409,9 @@ function initializeDatabase(file) {
     if (!publicationColumns.has("status")) {
         database.exec("ALTER TABLE snapshot_publications ADD COLUMN status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'rejected'))");
     }
+    if (!publicationColumns.has("submitted_at")) {
+        database.exec("ALTER TABLE snapshot_publications ADD COLUMN submitted_at INTEGER");
+    }
     database.exec("DROP INDEX IF EXISTS record_inbox_delivery");
     database.exec("DROP TABLE IF EXISTS mutation_journal");
     migratedDatabases.add(file);
@@ -2303,6 +2453,31 @@ function readGroundRowsForRoots(file, table, rootUUIDs) {
         database.close();
     }
 }
+/** Exact ground rows for a UUID set, batched under SQLite's parameter bound.
+ * Upload resolves each traveling artifact's source path and recorded size
+ * from these rows — content bytes live in the ground itself, never in a
+ * staged register copy. */
+function readGroundRowsByUuid(file, uuids) {
+    if (!existsSync(file) || uuids.length === 0)
+        return new Map();
+    const database = initializeDatabase(file);
+    try {
+        const found = new Map();
+        for (let start = 0; start < uuids.length; start += 500) {
+            const batch = uuids.slice(start, start + 500);
+            const rows = database.prepare(`
+        SELECT ${GROUND_ROW_PROJECTION}
+          FROM entities WHERE uuid IN (${batch.map(() => "?").join(", ")})
+      `).all(...batch);
+            for (const row of rows)
+                found.set(row.uuid, row);
+        }
+        return found;
+    }
+    finally {
+        database.close();
+    }
+}
 /** Type and UUID settle locally even when immutable repository capture must
  * retry. Those rows are identity evidence for the next observation, while
  * their absence from the notebook still means no verified logical result has
@@ -2687,7 +2862,8 @@ function readSnapshotPublications(file) {
     try {
         return database.prepare(`
       SELECT mutation_id AS mutationId, resource_id AS resourceId,
-             publication_json AS publicationJson, status
+             publication_json AS publicationJson, status,
+             submitted_at AS submittedAt
         FROM snapshot_publications ORDER BY sequence
     `).all().map((row) => {
             const publication = JSON.parse(row.publicationJson);
@@ -2714,6 +2890,7 @@ function readSnapshotPublications(file) {
                 replacementRootIds: publication.replacementRootIds.map(String),
                 replacementRecords: snapshotFromRecords(publication.replacementRecords).records,
                 status: row.status === "rejected" ? "rejected" : "pending",
+                submitted: row.submittedAt !== null,
             };
         });
     }
@@ -2857,26 +3034,28 @@ function commitDetectedState(file, input) {
     }
 }
 /** Journal the newest snapshot publication for its resource. A journal row
- * has exactly two meanings: `pending` — the submit outcome is unknown, so
- * the same mutation id must retry until the authority answers (the mutation
- * may already be accepted with only the acknowledgement lost); `rejected` —
- * the authority conclusively refused it, so it is never replayed. Only a
- * rejected row may be superseded — last write wins — and supersession and
- * insertion share one transaction, so a crash leaves exactly one durable
- * intent. Content uploads are content-addressed and idempotent, so a
- * superseded row loses no uploaded work. */
+ * has exactly three meanings: `pending` and never submitted — a local intent
+ * the authority has never seen, superseded freely (last write wins);
+ * `pending` and submitted — the submit outcome is unknown, so the same
+ * mutation id must retry until the authority answers (the mutation may
+ * already be accepted with only the acknowledgement lost) and nothing may
+ * supersede it; `rejected` — the authority conclusively refused it, so it is
+ * never replayed and awaits supersession. Supersession and insertion share
+ * one transaction, so a crash leaves exactly one durable intent. Content
+ * uploads are content-addressed and idempotent, so a superseded row loses no
+ * uploaded work. */
 function supersedeSnapshotJournal(file, entry) {
     const database = initializeDatabase(file);
     try {
         database.transaction(() => {
             const unresolved = database.prepare(`
         SELECT 1 AS present FROM snapshot_publications
-          WHERE resource_id = ? AND status = 'pending' LIMIT 1
+          WHERE resource_id = ? AND status = 'pending' AND submitted_at IS NOT NULL LIMIT 1
       `).get(entry.resourceId);
             if (unresolved) {
-                throw new Error("a pending publication with an unknown outcome must resolve before supersession");
+                throw new Error("a submitted publication with an unknown outcome must resolve before supersession");
             }
-            database.prepare("DELETE FROM snapshot_publications WHERE resource_id = ? AND status = 'rejected'")
+            database.prepare("DELETE FROM snapshot_publications WHERE resource_id = ?")
                 .run(entry.resourceId);
             database.prepare(`
         INSERT INTO snapshot_publications(
@@ -2898,6 +3077,19 @@ function supersedeSnapshotJournal(file, entry) {
         database.close();
     }
 }
+/** Durably declare a submit attempt before the first frame leaves. From this
+ * moment the row's outcome may exist only at the authority, so it must retry
+ * the same mutation id and may never be superseded or rebuilt locally. */
+function markSnapshotJournalSubmitted(file, mutationId) {
+    const database = initializeDatabase(file);
+    try {
+        database.prepare("UPDATE snapshot_publications SET submitted_at = ? WHERE mutation_id = ?")
+            .run(Date.now(), mutationId);
+    }
+    finally {
+        database.close();
+    }
+}
 /** Settle a journal row as conclusively refused. It is never replayed again;
  * a newer complete snapshot supersedes it on the next publication. */
 function markSnapshotJournalRejected(file, mutationId) {
@@ -2919,6 +3111,32 @@ function conclusivelyRefused(error) {
         return error.retryable === false;
     return error instanceof Error && conclusivelyRefused(error.cause);
 }
+/** Ground moved between capture and upload: a source no longer yields the
+ * bytes its recorded content head names, so the publication built on that
+ * capture can never complete. It was never submitted, so the lawful recovery
+ * is a fresh walk — capture current ground and publish that truth instead. */
+class StaleCaptureError extends Error {
+    constructor(detail, options) {
+        super(`captured ground moved before upload: ${detail}`, options);
+    }
+}
+function staleCapture(error) {
+    if (error instanceof StaleCaptureError)
+        return true;
+    return error instanceof Error && staleCapture(error.cause);
+}
+/** Local read evidence disagreeing with the recorded content head — the
+ * upload law's typed mismatch or the source file being gone entirely. */
+function sourceMismatch(error) {
+    const code = error?.code;
+    return code === "UPLOAD_SOURCE_MISMATCH" || code === "ENOENT";
+}
+/** The walked file moved while its bytes were being captured — ordinary
+ * ground behavior, answered by recapturing what stands there now. */
+function captureChurn(error) {
+    const code = error?.code;
+    return code === "CAPTURE_SOURCE_CHANGED" || code === "ENOENT";
+}
 function deleteJournalEntry(file, mutationId) {
     const database = initializeDatabase(file);
     try {
@@ -3389,6 +3607,7 @@ async function reconcileGround(input) {
     const notebookRemovals = new Set();
     const detection = [];
     const transferFailures = [];
+    const largeManifests = new Map();
     const scan = async (parameters) => {
         const counters = {
             entries: 0,
@@ -3466,6 +3685,8 @@ async function reconcileGround(input) {
                 : coreSuspicion,
             existingRows: existing.filter((row) => row.rootUUID === coreUUID),
             suspicion: observationFor(userRoot),
+            plansSendRecords: suspicions !== undefined,
+            largeManifests,
         });
     }
     const physicalRoots = registrationOwner ? [registrationOwner] : outerBoundRoots;
@@ -3501,6 +3722,11 @@ async function reconcileGround(input) {
             existingRows: existingWorkspaceRows,
             registeredBoundaries,
             suspicion: observationFor(rootPath),
+            // A register scan publishes one complete snapshot; it never mints Send
+            // records for the same initial contents, so it plans no detection and
+            // stages no cache bytes — upload reads the ground itself.
+            plansSendRecords: suspicions !== undefined && registrationWorkspaceId === undefined,
+            largeManifests,
         });
     }
     const changedUUIDs = new Set([
@@ -3524,10 +3750,11 @@ async function reconcileGround(input) {
         notebookRemovals: [...notebookRemovals],
         publicationRootIds: selectedRoots ? [...selectedRoots] : null,
         transferFailures,
+        largeManifests,
     };
 }
 async function reconcileRoot(input) {
-    const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, suspects = null, evidence, } = input;
+    const { identity, resourceId, rootUUID, rootName, rootPath, rootType, database, cacheDir, policy, bindingDir, suspects = null, evidence, plansSendRecords, largeManifests, } = input;
     // Prior rows reach this scan from every binding this root encloses. A row's
     // stored relativePath is relative to the root that last committed it, which
     // is a different frame when an enclosing boundary was just registered
@@ -3567,7 +3794,7 @@ async function reconcileRoot(input) {
             transferable: true,
             transferFailure: null,
             notebookRemovals: [],
-            detection: input.suspicion ? planGroundDetection({
+            detection: input.suspicion && plansSendRecords ? planGroundDetection({
                 rootId: rootUUID,
                 suspicion: input.suspicion,
                 before: existingRows.map(portableRecord),
@@ -3695,6 +3922,11 @@ async function reconcileRoot(input) {
         return [...new Set(paths)].sort();
     };
     let visitedEntries = 0;
+    // File captures overlap reads and hashing across a bounded pool while the
+    // directory traversal itself stays ordered and serial. Each task settles
+    // its own entry in place; every task is awaited before entries are read.
+    const captureTasks = [];
+    const captureGate = concurrencyGate(WALK_CAPTURE_CONCURRENCY);
     const visit = async (directory, parentUUID, parentType, base = "", activeRepository = parentType === "repo.git"
         ? {
             root: directory,
@@ -3770,6 +4002,7 @@ async function reconcileRoot(input) {
             let type;
             let payloadVersion = null;
             let linkTarget;
+            let deferredCapture = false;
             let contentVerifiedAtMs = existing?.contentVerifiedAtMs ?? null;
             if (!observe && existing && !stats.isDirectory()) {
                 type = existing.type;
@@ -3795,7 +4028,7 @@ async function reconcileRoot(input) {
                         linkTarget = readlinkSync(absolutePath);
                         const bytes = Buffer.from(linkTarget, "utf8");
                         payloadVersion = sha256Hex(bytes);
-                        if (!activeRepository)
+                        if (!activeRepository && plansSendRecords)
                             sealCapturedArtifact(cacheDir, {
                                 entityId: uuid,
                                 entityType: type,
@@ -3815,9 +4048,10 @@ async function reconcileRoot(input) {
                 }
                 else {
                     evidence && (evidence.contentReads += 1);
-                    const captured = await captureContentFile(absolutePath, stats, activeRepository ? null : cacheDir);
-                    type = classifyFile({ binary: captured.binary });
-                    payloadVersion = captured.contentHash;
+                    // Provisional identity; the pooled capture scheduled below settles
+                    // type, content head, and fingerprint before entries are read.
+                    type = "file.binary";
+                    deferredCapture = true;
                 }
             }
             else {
@@ -3839,6 +4073,44 @@ async function reconcileRoot(input) {
                 ...(linkTarget !== undefined ? { linkTarget } : {}),
                 ...statFingerprint(stats),
             });
+            if (deferredCapture) {
+                const entry = entries[entries.length - 1];
+                captureTasks.push(captureGate(async () => {
+                    let current = stats;
+                    for (let attempt = 1;; attempt++) {
+                        try {
+                            const captured = await captureContentFile(absolutePath, current, activeRepository || !plansSendRecords ? null : cacheDir);
+                            entry.type = classifyFile({ binary: captured.binary });
+                            entry.payloadVersion = captured.contentHash;
+                            entry.contentVerifiedAtMs = Date.now();
+                            Object.assign(entry, statFingerprint(current));
+                            if (captured.bytes > CHUNK_BYTES) {
+                                largeManifests?.set(captured.contentHash, captured.manifest);
+                            }
+                            return;
+                        }
+                        catch (error) {
+                            if (!captureChurn(error))
+                                throw error;
+                            if (attempt >= REGISTER_STALE_CAPTURE_ATTEMPTS) {
+                                throw new StaleCaptureError(`${absolutePath} kept changing while being captured`, { cause: error });
+                            }
+                            // The file moved mid-read. Capture what stands there now —
+                            // the walk publishes point-in-time truth, not the first bytes
+                            // it happened to observe.
+                            try {
+                                current = lstatSync(absolutePath);
+                            }
+                            catch (statError) {
+                                throw new StaleCaptureError(`${absolutePath} disappeared during capture`, { cause: statError });
+                            }
+                            if (!current.isFile()) {
+                                throw new StaleCaptureError(`${absolutePath} is no longer a file`, { cause: error });
+                            }
+                        }
+                    }
+                }));
+            }
             if (stats.isDirectory() && !stats.isSymbolicLink()) {
                 const childRailChanged = existing !== undefined && existing.type !== type;
                 await visit(absolutePath, uuid, type, relativePath, type === "repo.git"
@@ -3852,6 +4124,7 @@ async function reconcileRoot(input) {
         }
     };
     await visit(rootPath, rootUUID, rootType);
+    await Promise.all(captureTasks);
     // When every entry sits at its stored address with its stored type and
     // physical fingerprint (honoring any fixed UUID), path-first claiming makes
     // the multi-pass reconciliation the identity map — resolve directly. Any
@@ -3987,7 +4260,17 @@ async function reconcileRoot(input) {
                 for (const path of registration.dirtyPaths) {
                     const entry = ownedByPath.get(path);
                     const absolutePath = join(repository.absolutePath, ...path.split("/"));
-                    if (!existsSync(absolutePath)) {
+                    // Existence must observe the path itself: a tracked symlink with an
+                    // absent target is present ground, never a deleted entry.
+                    let stats = null;
+                    try {
+                        stats = lstatSync(absolutePath);
+                    }
+                    catch (error) {
+                        if (error.code !== "ENOENT")
+                            throw error;
+                    }
+                    if (stats === null) {
                         if (entry)
                             removed.add(path);
                         continue;
@@ -3995,7 +4278,6 @@ async function reconcileRoot(input) {
                     if (!entry) {
                         throw new Error(`repository dirty path ${path} has no registered identity`);
                     }
-                    const stats = lstatSync(absolutePath);
                     if (stats.isSymbolicLink()) {
                         const target = readlinkSync(absolutePath);
                         entry.type = "link";
@@ -4229,7 +4511,9 @@ async function reconcileRoot(input) {
     const before = existingRows.map(portableRecord);
     const beforeByUuid = new Map(before.map((record) => [record.uuid, record]));
     const entryByUuid = new Map(entries.map((entry) => [entry.uuid, entry]));
-    const detected = rows.map((row) => {
+    // Replays exist to mint Send records; a scan that plans none builds none —
+    // and its walk staged no cache bytes for replays to read.
+    const detected = !plansSendRecords ? [] : rows.map((row) => {
         const base = beforeByUuid.get(row.record.uuid) ?? null;
         const entry = entryByUuid.get(row.record.uuid);
         if (row.record.type !== "repo.git" && entry && territory.ownerOf(entry)) {
@@ -4324,7 +4608,7 @@ async function reconcileRoot(input) {
         transferable: true,
         transferFailure: null,
         notebookRemovals,
-        detection: input.suspicion ? planGroundDetection({
+        detection: input.suspicion && plansSendRecords ? planGroundDetection({
             rootId: rootUUID,
             suspicion: input.suspicion,
             before: plannedBefore,
@@ -5031,4 +5315,25 @@ async function boundedForEach(items, concurrency, perform) {
     };
     await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
 }
+/** Admit queued async tasks with at most `limit` in flight. Scheduling never
+ * blocks the caller; each task's settlement is its returned promise. The
+ * admitted task re-checks the bound because a released slot may be claimed
+ * synchronously before a woken waiter resumes. */
+function concurrencyGate(limit) {
+    let active = 0;
+    const waiting = [];
+    return async (task) => {
+        while (active >= limit) {
+            await new Promise((grant) => waiting.push(grant));
+        }
+        active += 1;
+        try {
+            return await task();
+        }
+        finally {
+            active -= 1;
+            waiting.shift()?.();
+        }
+    };
+}
 //# sourceMappingURL=user-ground-host.js.map