@amalgm/shell 0.1.68 → 0.1.70

package/dist/user-ground-host.js

@@ -3,10 +3,10 @@ import { existsSync, lstatSync, realpathSync, readFileSync, readdirSync, readlin
 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, CONTENT_CONTRACT, ENTITY_CLOUD_CONTRACT, ENTITY_CLOUD_SCHEMA_VERSION, artifactForRecord, canonicalVersion, checkContentManifest, classifyDirectory, classifyFile, classifyRegisteredRoot, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, download as downloadArtifact, encodeEntityRecord, EntityApplyRail, EntityRecordRail, 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, createLocalEntityRecord, createEntityRecordAuthorityPort, convergeUserGround, createUserGroundEnrollmentPolicy, isRepositoryMetadataEntry, indexRepositoryTerritory, download as downloadArtifact, encodeEntityRecord, EntityApplyRail, EntityRecordRail, membershipHash, parseSnapshot, pathIsSuspect, privateEntityResourceId, rootReplacementFromRecords, sameRecords, snapshotFromRecords, stableJson, travelingRecords, upload as uploadArtifact, userGroundRecords, } from "@amalgm/live";
 import Database from "better-sqlite3";
 import { atomicCopy, atomicWrite, ensurePrivateDir } from "./filesystem.js";
-import { EntityApplyHost } from "./entity-apply-host.js";
+import { EntityApplyHost, } from "./entity-apply-host.js";
 import { EntityRecordSqliteStore } from "./entity-record-store.js";
 import { indexRowsByOutermostRoot } from "./ground-root-index.js";
 import { ContentCacheDownload, captureContentFile, hashContentFile, sealCapturedArtifact, } from "./content-cache-host.js";
@@ -26,6 +26,8 @@ const FILE_BATCH_DOWNLOAD_CONCURRENCY = 2;
 const DETECT_QUIET_MS = 12;
 const DETECT_MAX_DEFERRAL_MS = 75;
 const DETECT_RETRY_MS = 250;
+const DOWNLOAD_CONTENT_RETRY_ATTEMPTS = 3;
+const APPLY_GROUND_WAIT_TIMEOUT_MS = 15_000;
 const GROUND_ROW_COLUMNS = [
     "uuid", "resource_id", "root_uuid", "type", "parent_uuid", "name", "status", "version",
     "payload_version", "transport_version", "relative_path", "absolute_path", "device_number",
@@ -60,6 +62,7 @@ export class UserGroundHost {
             url: options.tunnelUrl,
             token: options.tunnelToken,
             runtimeVersion: options.runtimeVersion,
+            requestTimeoutMs: options.wireRequestTimeoutMs,
         });
         this.watchHost = new NodeWatchHost({
             open: options.openWatch,
@@ -332,7 +335,10 @@ export class UserGroundHost {
                 notebookRemovals: scanned.notebookRemovals,
             });
             this.namedDetect?.refreshEnrollmentPolicy();
-            await this.publishMaterializedSnapshot(identity);
+            if (!scanned.publicationRootIds) {
+                throw new Error("cold registration reconciliation did not name its publication roots");
+            }
+            await this.publishMaterializedSnapshot(identity, new Set(scanned.publicationRootIds));
             this.watchHost.settle(observations);
         }
         catch (error) {
@@ -476,7 +482,7 @@ export class UserGroundHost {
             userRoot: this.userRoot(identity),
             cacheDir: this.cacheDir(identity),
             bindingDir: workspaceBindingDir(this.userRoot(identity), identity.deviceId),
-            readContent: (artifact) => this.downloadContent(this.cloudState.resourceId, this.cacheDir(identity), artifact),
+            readContent: (artifact) => this.downloadContent(this.cloudState.resourceId, this.cacheDir(identity), artifact, DOWNLOAD_CONTENT_RETRY_ATTEMPTS),
             captureLocal: async (intent, plan, position) => {
                 // Apply never suppresses Watch. This explicit whole-root suspicion is
                 // the synchronous proof boundary used only when Apply observed a
@@ -488,7 +494,9 @@ export class UserGroundHost {
                     throw new Error(`Apply ${position} capture for ${plan.target.type} ${plan.target.name} (${intent.entityId}) produced no durable local record`);
                 }
             },
-            acquireGround: () => this.acquireGroundEffect(),
+            acquireGround: () => this.acquireGroundEffect(APPLY_GROUND_WAIT_TIMEOUT_MS),
+            onStage: (evidence) => this.options.onApplyStage?.(evidence),
+            now: () => this.options.now?.().getTime() ?? Date.now(),
         });
         const rail = new EntityApplyRail({
             store: host.store,
@@ -503,6 +511,7 @@ export class UserGroundHost {
             },
             sha256Hex,
             now: Date.now,
+            onBackgroundError: (error) => this.options.onApplyError?.(error),
             // Path cones and repository territories are wider than one UUID. Until
             // the host exposes those locks, one serial machine-effect owner is the
             // only honest concurrency setting.
@@ -815,7 +824,7 @@ export class UserGroundHost {
             await transfer(source);
         }
     }
-    async downloadContent(resourceId, cacheDir, artifact) {
+    async downloadContent(resourceId, cacheDir, artifact, retryAttempts = 10) {
         const cache = { target: null };
         const getChunk = async (manifest, index) => {
             const chunk = manifest.chunks[index];
@@ -829,7 +838,7 @@ export class UserGroundHost {
                 kind: "chunk",
                 part_index: index,
                 sha256: chunk.sha256,
-            }, ["private.entity-content.data"]), true);
+            }, ["private.entity-content.data"]), true, retryAttempts);
             return binaryFrameBytes(frame);
         };
         try {
@@ -842,7 +851,7 @@ export class UserGroundHost {
                         content_hash: artifact.contentHash,
                         kind: "manifest",
                         part_index: 0,
-                    }, ["private.entity-content.data"]));
+                    }, ["private.entity-content.data"]), false, retryAttempts);
                     const candidate = JSON.parse(verifiedFrameBytes(frame).toString("utf8"));
                     const checked = checkContentManifest(candidate, artifact.contentHash);
                     if (!checked.ok)
@@ -873,7 +882,7 @@ export class UserGroundHost {
                             sha256: manifest.chunks[index]?.sha256,
                             bytes: manifest.chunks[index]?.bytes,
                         })),
-                    }, ["private.entity-content.data-batch"]), true);
+                    }, ["private.entity-content.data-batch"]), true, retryAttempts);
                     return decodeContentWireBytes(binaryWireFrameBytes(frame), frame.content_encoding, Number(frame.bytes));
                 },
                 putChunk: async (_candidate, _manifest, index, bytes) => {
@@ -976,13 +985,49 @@ export class UserGroundHost {
             this.scheduleRescan();
         }
     }
-    async acquireGroundEffect() {
+    async acquireGroundEffect(timeoutMs) {
         let release;
         const held = new Promise((resolve) => { release = resolve; });
         const preceding = this.groundEffectTail;
         this.groundEffectTail = preceding.then(() => held);
-        await preceding;
-        return release;
+        let released = false;
+        const releaseOnce = () => {
+            if (released)
+                return;
+            released = true;
+            release();
+        };
+        if (timeoutMs === undefined) {
+            await preceding;
+            return releaseOnce;
+        }
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+            // This queued slot has not become active. Let it pass through as soon as
+            // the preceding owner finishes so invalid input cannot poison the tail.
+            void preceding.then(releaseOnce, releaseOnce);
+            throw new Error("ground-effect wait timeout must be a positive integer");
+        }
+        let timeout = null;
+        try {
+            await Promise.race([
+                preceding,
+                new Promise((_resolve, reject) => {
+                    timeout = setTimeout(() => reject(new Error(`ground-effect wait exceeded ${timeoutMs}ms`)), timeoutMs);
+                }),
+            ]);
+            return releaseOnce;
+        }
+        catch (error) {
+            // The timed-out waiter still owns one FIFO slot. Automatically release
+            // that slot when it reaches the front; otherwise one timeout would block
+            // every later filesystem effect forever.
+            void preceding.then(releaseOnce, releaseOnce);
+            throw error;
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+        }
     }
     async syncLocalChanges(identity) {
         const release = await this.acquireGroundEffect();
@@ -1100,11 +1145,13 @@ export class UserGroundHost {
     /** Register is the deliberate cold graph-publication boundary. Ordinary
      * Watch detection stops at a durable exact record and never rebuilds this
      * resource snapshot. */
-    async publishMaterializedSnapshot(identity) {
+    async publishMaterializedSnapshot(identity, publicationRootIds) {
         const state = this.cloudState;
         if (!state)
             throw new Error("cloud state is unavailable for graph publication");
-        const localRecords = recordsRetainingMissingEvidence(portableRecords(this.databasePath(identity)), readPortableRecords(this.databasePath(identity), "detection_notebook"));
+        const localRecords = recordsRetainingMissingEvidence(readGroundRowsForRoots(this.databasePath(identity), "entities", publicationRootIds)
+            .map(portableRecord), readGroundRowsForRoots(this.databasePath(identity), "detection_notebook", publicationRootIds)
+            .map(portableRecord));
         const merged = mergeMaterializedRoots(state.records, localRecords);
         const traveling = travelingRecords(merged);
         const impossibleGitLeaf = traveling.find((record) => (record.type === "file.text" || record.type === "file.binary" || record.type === "link")
@@ -1129,6 +1176,16 @@ export class UserGroundHost {
             throw new Error("a different graph snapshot is already pending publication");
         }
         const localIds = new Set(localRecords.map((record) => record.uuid));
+        const replacementRootIds = localRecords
+            .filter((record) => record.parentUUID === null)
+            .map((record) => record.uuid);
+        const replacementRoots = new Set(replacementRootIds);
+        const rootOf = recordRootResolver(snapshot.records);
+        const replacementRecords = snapshot.records.filter((record) => {
+            const root = rootOf(record);
+            return root !== null && replacementRoots.has(root);
+        });
+        const replacement = rootReplacementFromRecords(replacementRootIds, replacementRecords);
         const publishedArtifacts = new Set(state.records.flatMap((record) => {
             const artifact = artifactForRecord(record);
             return artifact ? [artifact.contentHash] : [];
@@ -1147,12 +1204,15 @@ export class UserGroundHost {
             snapshotChecksum: checksum,
             snapshotJson,
             uploadRecords,
+            replacementRootIds: replacement.rootIds,
+            replacementRecords: replacement.records,
         });
         await this.publishPendingSnapshots(identity);
     }
     async publishPendingSnapshots(identity) {
         for (const pending of readSnapshotPublications(this.databasePath(identity))) {
             const snapshot = snapshotFromRecords(JSON.parse(pending.snapshotJson).records || []);
+            const replacement = rootReplacementFromRecords(pending.replacementRootIds, pending.replacementRecords);
             try {
                 await this.uploadSnapshotContent(identity, pending.resourceId, pending.uploadRecords);
             }
@@ -1171,8 +1231,8 @@ export class UserGroundHost {
                         baseVersion: pending.baseVersion,
                         contract: ENTITY_CLOUD_CONTRACT,
                         schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
-                        operationKind: "entity.snapshot.replace",
-                        operation: { kind: "entity.snapshot.replace", snapshot },
+                        operationKind: replacement.kind,
+                        operation: replacement,
                     },
                 }, ["shared.mutation.ack"]);
             }
@@ -1701,6 +1761,10 @@ function readSnapshotPublications(file) {
             if (!Array.isArray(publication.uploadRecords)) {
                 throw new Error(`snapshot publication ${row.mutationId} has no exact upload subset`);
             }
+            if (!Array.isArray(publication.replacementRootIds)
+                || !Array.isArray(publication.replacementRecords)) {
+                throw new Error(`snapshot publication ${row.mutationId} has no exact root replacement`);
+            }
             return {
                 mutationId: row.mutationId,
                 resourceId: row.resourceId,
@@ -1709,6 +1773,8 @@ function readSnapshotPublications(file) {
                 snapshotChecksum: String(publication.snapshotChecksum),
                 snapshotJson: String(publication.snapshotJson),
                 uploadRecords: snapshotFromRecords(publication.uploadRecords).records,
+                replacementRootIds: publication.replacementRootIds.map(String),
+                replacementRecords: snapshotFromRecords(publication.replacementRecords).records,
             };
         });
     }
@@ -1796,6 +1862,8 @@ function appendSnapshotJournal(file, entry) {
             snapshotChecksum: entry.snapshotChecksum,
             snapshotJson: entry.snapshotJson,
             uploadRecords: entry.uploadRecords,
+            replacementRootIds: entry.replacementRootIds,
+            replacementRecords: entry.replacementRecords,
         }), Date.now());
     }
     finally {
@@ -2334,6 +2402,7 @@ async function reconcileGround(input) {
         materializedRemovals: [...materializedRemovals],
         acceptedNotebookRows,
         notebookRemovals: [...notebookRemovals],
+        publicationRootIds: selectedRoots ? [...selectedRoots] : null,
     };
 }
 async function reconcileRoot(input) {
@@ -3568,9 +3637,12 @@ function verifiedFrameBytes(frame) {
 /** Immutable content reads and writes are idempotent. Retry transient wire or
  * authority failures; reads additionally tolerate the brief not-found window
  * between an immutable object acknowledgement and globally visible R2 state. */
-async function retryContent(operation, eventualNotFound = false) {
+async function retryContent(operation, eventualNotFound = false, attempts = 10) {
+    if (!Number.isSafeInteger(attempts) || attempts < 1) {
+        throw new Error("content retry attempts must be a positive integer");
+    }
     let last;
-    for (let attempt = 0; attempt < 10; attempt += 1) {
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
         try {
             return await operation();
         }