@amalgm/shell 0.1.73 → 0.1.74

package/dist/user-ground-host.js

@@ -6,8 +6,10 @@ import { buildUserHomeManifest, buildUserManifest, liveMachineStateDir, scopedAm
 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 { emitFilesStage, } from "./files-observability.js";
 import { EntityApplyHost, } from "./entity-apply-host.js";
 import { EntityRecordSqliteStore } from "./entity-record-store.js";
+import { observeEntityRecordPorts } from "./entity-record-observability.js";
 import { indexRowsByOutermostRoot } from "./ground-root-index.js";
 import { ContentCacheDownload, captureContentFile, hashContentFile, sealCapturedArtifact, } from "./content-cache-host.js";
 import { decodeContentWireBytes, encodeContentWireBytes } from "./content-wire-codec.js";
@@ -67,7 +69,29 @@ export class UserGroundHost {
         this.watchHost = new NodeWatchHost({
             open: options.openWatch,
             onSignal: () => this.scheduleRescan(),
-            onHealth: options.onWatchHealth,
+            onEvent: (evidence) => this.stage({
+                primitive: "watch",
+                stage: "native-suspicion",
+                status: "observed",
+                path: evidence.path === null
+                    ? evidence.directory
+                    : join(evidence.directory, ...evidence.path.split("/")),
+                measurements: { kind: evidence.kind, named: evidence.path !== null },
+            }),
+            onHealth: (health) => {
+                options.onWatchHealth?.(health);
+                this.stage({
+                    primitive: "watch",
+                    stage: "coverage-health",
+                    status: "observed",
+                    measurements: {
+                        state: health.state,
+                        logicalRoots: health.logicalRoots,
+                        contentHandles: health.contentHandles,
+                        addressHandles: health.addressHandles,
+                    },
+                });
+            },
         });
         this.port = {
             converge: async (identity) => {
@@ -80,7 +104,29 @@ export class UserGroundHost {
                     local,
                 });
                 await this.resumeWorkspaceAdds(this.activeIdentity);
-                this.namedDetect ??= new NamedDetectRuntime(this.databasePath(this.activeIdentity), this.cacheDir(this.activeIdentity), this.userRoot(this.activeIdentity));
+                this.namedDetect ??= new NamedDetectRuntime(this.databasePath(this.activeIdentity), this.cacheDir(this.activeIdentity), this.userRoot(this.activeIdentity), ({ durationMs, records }) => {
+                    if (records.length === 0) {
+                        this.stage({
+                            primitive: "record",
+                            stage: "sqlite-transaction",
+                            status: "completed",
+                            durationMs,
+                            measurements: { records: 0 },
+                        });
+                        return;
+                    }
+                    for (const record of records) {
+                        this.stage({
+                            primitive: "record",
+                            stage: "outbox-committed",
+                            status: "completed",
+                            entityId: record.entityId,
+                            mutationId: record.mutationId,
+                            durationMs,
+                            measurements: { records: records.length },
+                        });
+                    }
+                });
                 const watchHealth = this.watchHost.health();
                 if (watchHealth.state !== "healthy") {
                     throw new Error(`Watch coverage is degraded: ${watchHealth.reason ?? "unknown failure"}`);
@@ -103,6 +149,30 @@ export class UserGroundHost {
             },
         };
     }
+    stage(input) {
+        emitFilesStage(this.options.onFilesStage, input);
+    }
+    reportDetectScan(evidence) {
+        this.options.onDetectScan?.(evidence);
+        this.stage({
+            primitive: "detect",
+            stage: "scan",
+            status: "completed",
+            rootId: evidence.rootId,
+            path: evidence.directory,
+            durationMs: evidence.durationMs,
+            measurements: {
+                scope: evidence.scope,
+                entries: evidence.entries,
+                metadataReused: evidence.metadataReused,
+                contentReads: evidence.contentReads,
+                gitInspections: evidence.gitInspections,
+                repositoryCaptures: evidence.repositoryCaptures,
+                records: evidence.records ?? 0,
+                recordBytes: evidence.recordBytes ?? 0,
+            },
+        });
+    }
     databasePath(identity) {
         return join(liveMachineStateDir(this.userRoot(identity), identity.deviceId), "identity.db");
     }
@@ -151,14 +221,39 @@ export class UserGroundHost {
         });
         const add = {
             lookupRegistry: async () => {
+                const started = performance.now();
+                this.stage({
+                    primitive: "download", stage: "registry-lookup", status: "started",
+                });
                 const resourceId = privateEntityResourceId(identity.userId, sha256Hex);
                 const cloud = await this.cloudPort(identity).lookup(resourceId);
                 if (!cloud)
                     throw new Error("this user has no cloud entity registry");
+                this.stage({
+                    primitive: "download",
+                    stage: "registry-lookup",
+                    status: "completed",
+                    durationMs: performance.now() - started,
+                });
                 return cloud;
             },
             materializeWorkspace: async (input) => {
+                const groundWaitStarted = performance.now();
+                this.stage({
+                    primitive: "download",
+                    stage: "ground-wait",
+                    status: "started",
+                    workspaceId: input.workspace.uuid,
+                });
                 const release = await this.acquireGroundEffect();
+                this.stage({
+                    primitive: "download",
+                    stage: "ground-wait",
+                    status: "completed",
+                    workspaceId: input.workspace.uuid,
+                    durationMs: performance.now() - groundWaitStarted,
+                });
+                let milestoneAt = performance.now();
                 try {
                     const installed = await installCloudWorkspace({
                         identity,
@@ -173,11 +268,22 @@ export class UserGroundHost {
                         records: input.records,
                         destinationParent: input.destinationParent,
                         cloudHead: input.cloudHead,
-                        readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact),
-                        onStage: (stage) => this.options.onWorkspaceAddStage?.({
-                            workspaceId: input.workspace.uuid,
-                            stage,
-                        }),
+                        readContent: (artifact) => this.downloadContent(privateEntityResourceId(identity.userId, sha256Hex), this.cacheDir(identity), artifact, 10, { journey: "add", workspaceId: input.workspace.uuid }),
+                        onStage: async (stage) => {
+                            const now = performance.now();
+                            this.stage({
+                                primitive: stage === "watching" ? "watch" : "download",
+                                stage,
+                                status: "completed",
+                                workspaceId: input.workspace.uuid,
+                                durationMs: now - milestoneAt,
+                            });
+                            milestoneAt = now;
+                            await this.options.onWorkspaceAddStage?.({
+                                workspaceId: input.workspace.uuid,
+                                stage,
+                            });
+                        },
                     });
                     // Add changes both disk and the exact SQLite projection. Open the
                     // selected root's singular Watch coverage before Detect can observe
@@ -192,6 +298,10 @@ export class UserGroundHost {
                 }
             },
             coverWorkspace: async ({ workspaceId, baseline }) => {
+                const started = performance.now();
+                this.stage({
+                    primitive: "watch", stage: "add-coverage", status: "started", workspaceId,
+                });
                 const pending = readWorkspaceAddIntent(this.databasePath(identity), workspaceId);
                 const health = this.ensureWatchers(identity, pending || baseline === "authoritative-install" ? [workspaceId] : []);
                 assertHealthyWatch(this.watchHost.evidence(), workspaceId);
@@ -199,6 +309,17 @@ export class UserGroundHost {
                     await this.options.onWorkspaceAddStage?.({ workspaceId, stage: "watching" });
                     deleteWorkspaceAddIntent(this.databasePath(identity), workspaceId);
                 }
+                this.stage({
+                    primitive: "watch",
+                    stage: "add-coverage",
+                    status: "completed",
+                    workspaceId,
+                    durationMs: performance.now() - started,
+                    measurements: {
+                        contentHandles: health.contentHandles,
+                        addressHandles: health.addressHandles,
+                    },
+                });
                 return { active: true, roots: health.contentHandles };
             },
         };
@@ -236,7 +357,7 @@ export class UserGroundHost {
                     records: intent.records,
                     destinationParent: dirname(intent.destinationPath),
                     cloudHead: intent.cloudHead,
-                    readContent: (artifact) => this.downloadContent(intent.resourceId, this.cacheDir(identity), artifact),
+                    readContent: (artifact) => this.downloadContent(intent.resourceId, this.cacheDir(identity), artifact, 10, { journey: "add", workspaceId: intent.workspaceId }),
                     onStage: (stage) => this.options.onWorkspaceAddStage?.({
                         workspaceId: intent.workspaceId,
                         stage,
@@ -277,9 +398,24 @@ export class UserGroundHost {
         this.rescanGenerationStartedAt = null;
         let watch;
         try {
+            const watchStarted = performance.now();
+            this.stage({
+                primitive: "watch", stage: "register-coverage", status: "started", workspaceId,
+            });
             this.ensureWatchers(identity);
             watch = this.watchHost.evidence();
             assertHealthyWatch(watch, workspaceId);
+            this.stage({
+                primitive: "watch",
+                stage: "register-coverage",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - watchStarted,
+                measurements: {
+                    contentHandles: watch.health.contentHandles,
+                    addressHandles: watch.health.addressHandles,
+                },
+            });
         }
         catch (error) {
             this.finishColdOperation();
@@ -305,9 +441,20 @@ export class UserGroundHost {
         // a parallel stream of Detect records for the same initial contents.
         let releaseGround = null;
         try {
+            const groundWaitStarted = performance.now();
+            this.stage({
+                primitive: "register", stage: "ground-wait", status: "started", workspaceId,
+            });
             if (this.syncing)
                 await this.syncing;
             releaseGround = await this.acquireGroundEffect();
+            this.stage({
+                primitive: "register",
+                stage: "ground-wait",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - groundWaitStarted,
+            });
             const contentOwner = watch.roots.find((root) => root.rootId === workspaceId)?.contentOwner;
             if (!contentOwner) {
                 throw new Error(`registered workspace ${workspaceId} has no content coverage owner`);
@@ -315,12 +462,16 @@ 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: this.options.onDetectScan,
+                onScan: (evidence) => this.reportDetectScan(evidence),
                 registrationWorkspaceId: workspaceId,
                 suspicions: new Map(observations.map((observation) => [observation.directory, observation.suspicion])),
             });
@@ -328,17 +479,39 @@ export class UserGroundHost {
             if (retry?.kind === "retry") {
                 throw new Error(retry.reasons.join("; "));
             }
+            this.stage({
+                primitive: "register",
+                stage: "entity-registration",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - registrationStarted,
+                measurements: {
+                    roots: scanned.publicationRootIds?.length ?? 0,
+                    rows: scanned.acceptedMaterializedRows.length,
+                },
+            });
+            const commitStarted = performance.now();
+            this.stage({
+                primitive: "register", stage: "entity-sqlite-commit", status: "started", workspaceId,
+            });
             commitDetectedState(this.databasePath(identity), {
                 acceptedMaterializedRows: scanned.acceptedMaterializedRows,
                 materializedRemovals: scanned.materializedRemovals,
                 acceptedNotebookRows: scanned.acceptedNotebookRows,
                 notebookRemovals: scanned.notebookRemovals,
             });
+            this.stage({
+                primitive: "register",
+                stage: "entity-sqlite-commit",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - commitStarted,
+            });
             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));
+            await this.publishMaterializedSnapshot(identity, new Set(scanned.publicationRootIds), { journey: "register", workspaceId });
             this.watchHost.settle(observations);
         }
         catch (error) {
@@ -353,9 +526,21 @@ export class UserGroundHost {
             this.finishColdOperation();
         }
         try {
+            const finalWatchStarted = performance.now();
             this.ensureWatchers(identity);
             watch = this.watchHost.evidence();
             assertHealthyWatch(watch, workspaceId);
+            this.stage({
+                primitive: "watch",
+                stage: "register-final-proof",
+                status: "completed",
+                workspaceId,
+                durationMs: performance.now() - finalWatchStarted,
+                measurements: {
+                    contentHandles: watch.health.contentHandles,
+                    addressHandles: watch.health.addressHandles,
+                },
+            });
         }
         catch (error) {
             throw stageError("Watch coverage", error);
@@ -434,18 +619,28 @@ export class UserGroundHost {
             throw new Error("gateway does not support the event-driven entity Record wire");
         }
         const store = new EntityRecordSqliteStore(initializeDatabase(this.databasePath(identity)));
-        const authority = createEntityRecordAuthorityPort({
+        const wireAuthority = createEntityRecordAuthorityPort({
             request: (frame, acceptedTypes) => this.wire.request({ ...frame }, acceptedTypes),
             onFrame: (listener) => this.wire.onEvent(listener),
             onDisconnect: (listener) => this.wire.onDisconnect(listener),
         });
-        const rail = new EntityRecordRail({
-            authorityId: this.cloudState.resourceId,
+        const ports = observeEntityRecordPorts({
             store,
-            authority,
+            authority: wireAuthority,
             cargo: {
-                ensure: (record) => this.uploadSnapshotContent(identity, record.authorityId, [record.change.result]),
+                ensure: (record) => this.uploadSnapshotContent(identity, record.authorityId, [record.change.result], {
+                    journey: "send",
+                    entityId: record.entityId,
+                    mutationId: record.mutationId,
+                }),
             },
+            onStage: this.options.onFilesStage,
+        });
+        const rail = new EntityRecordRail({
+            authorityId: this.cloudState.resourceId,
+            store: ports.store,
+            authority: ports.authority,
+            cargo: ports.cargo,
             schedule: {
                 schedule(delayMs, callback) {
                     const timer = setTimeout(callback, delayMs);
@@ -482,7 +677,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, DOWNLOAD_CONTENT_RETRY_ATTEMPTS),
+            readContent: (artifact) => this.downloadContent(this.cloudState.resourceId, this.cacheDir(identity), artifact, DOWNLOAD_CONTENT_RETRY_ATTEMPTS, { journey: "apply" }),
             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
@@ -495,7 +690,17 @@ export class UserGroundHost {
                 }
             },
             acquireGround: () => this.acquireGroundEffect(APPLY_GROUND_WAIT_TIMEOUT_MS),
-            onStage: (evidence) => this.options.onApplyStage?.(evidence),
+            onStage: (evidence) => {
+                this.options.onApplyStage?.(evidence);
+                this.stage({
+                    primitive: "apply",
+                    stage: evidence.stage,
+                    status: "observed",
+                    entityId: evidence.entityId,
+                    globalSequence: evidence.throughSequence,
+                    measurements: { type: evidence.type, phase: evidence.phase },
+                });
+            },
             now: () => this.options.now?.().getTime() ?? Date.now(),
         });
         const rail = new EntityApplyRail({
@@ -672,7 +877,7 @@ export class UserGroundHost {
                 });
                 await reconcileGround({
                     identity, userRoot, database, cacheDir,
-                    onScan: this.options.onDetectScan,
+                    onScan: (evidence) => this.reportDetectScan(evidence),
                 });
                 return localValue(identity, userRoot, database);
             },
@@ -693,7 +898,7 @@ export class UserGroundHost {
             },
         };
     }
-    async uploadSnapshotContent(identity, resourceId, records) {
+    async uploadSnapshotContent(identity, resourceId, records, trace) {
         const cache = this.cacheDir(identity);
         const byHash = new Map();
         for (const record of records) {
@@ -714,6 +919,27 @@ export class UserGroundHost {
                 bytes: manifest?.bytes ?? statSync(file).size,
             };
         });
+        const started = performance.now();
+        let uploadedChunks = 0;
+        let reusedChunks = 0;
+        let uploadedBytes = 0;
+        let inventoryRequests = 0;
+        const identifiers = {
+            ...(trace?.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+            ...(trace?.entityId ? { entityId: trace.entityId } : {}),
+            ...(trace?.mutationId ? { mutationId: trace.mutationId } : {}),
+        };
+        this.stage({
+            primitive: "upload",
+            stage: "immutable-content",
+            status: "started",
+            ...identifiers,
+            measurements: {
+                journey: trace?.journey ?? "bootstrap",
+                artifacts: sources.length,
+                declaredBytes: sources.reduce((total, source) => total + source.bytes, 0),
+            },
+        });
         const small = sources.filter((source) => source.bytes <= CHUNK_BYTES);
         const large = sources.filter((source) => source.bytes > CHUNK_BYTES);
         const transfer = async (source) => {
@@ -735,6 +961,7 @@ export class UserGroundHost {
                     sha256: chunk.sha256,
                     bytes: chunk.bytes,
                 }, bytes, ["private.entity-content.stored"]));
+                uploadedBytes += bytes.byteLength;
             };
             try {
                 const receipt = await uploadArtifact(artifact, {
@@ -752,6 +979,7 @@ export class UserGroundHost {
                 }, {
                     sha256Hex,
                     missingChunks: async (_candidate, manifest) => {
+                        inventoryRequests += 1;
                         const frame = await retryContent(() => this.wire.request({
                             type: "private.entity-content.inventory",
                             resource_id: resourceId,
@@ -794,6 +1022,7 @@ export class UserGroundHost {
                             wire_bytes: encoded.bytes.byteLength,
                             ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
                         }, encoded.bytes, ["private.entity-content.stored-batch"]));
+                        uploadedBytes += encoded.bytes.byteLength;
                     },
                     putManifest: async (_candidate, manifest) => {
                         if (manifestPresent)
@@ -810,8 +1039,11 @@ export class UserGroundHost {
                             sha256: sha256Hex(bytes),
                             bytes: bytes.length,
                         }, bytes, ["private.entity-content.stored"]));
+                        uploadedBytes += bytes.byteLength;
                     },
                 });
+                uploadedChunks += receipt.uploadedChunks;
+                reusedChunks += receipt.reusedChunks;
                 atomicWrite(manifestCacheFile(cache, artifact.contentHash), stableJson(receipt.manifest));
             }
             finally {
@@ -819,17 +1051,63 @@ export class UserGroundHost {
                     await (await sourceFile.handle).close();
             }
         };
-        await boundedForEach(small, SMALL_CONTENT_UPLOAD_CONCURRENCY, transfer);
-        for (const source of large) {
-            await transfer(source);
+        try {
+            await boundedForEach(small, SMALL_CONTENT_UPLOAD_CONCURRENCY, transfer);
+            for (const source of large) {
+                await transfer(source);
+            }
+            this.stage({
+                primitive: "upload",
+                stage: "immutable-content",
+                status: "completed",
+                ...identifiers,
+                durationMs: performance.now() - started,
+                measurements: {
+                    journey: trace?.journey ?? "bootstrap",
+                    artifacts: sources.length,
+                    declaredBytes: sources.reduce((total, source) => total + source.bytes, 0),
+                    uploadedBytes,
+                    uploadedChunks,
+                    reusedChunks,
+                    inventoryRequests,
+                },
+            });
+        }
+        catch (error) {
+            this.stage({
+                primitive: "upload",
+                stage: "immutable-content",
+                status: "failed",
+                ...identifiers,
+                durationMs: performance.now() - started,
+                measurements: { journey: trace?.journey ?? "bootstrap" },
+            });
+            throw error;
         }
     }
-    async downloadContent(resourceId, cacheDir, artifact, retryAttempts = 10) {
+    async downloadContent(resourceId, cacheDir, artifact, retryAttempts = 10, trace) {
+        const started = performance.now();
+        let downloadedBytes = 0;
+        let requests = 0;
+        const identifiers = {
+            ...(trace?.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+            entityId: trace?.entityId ?? artifact.entityId,
+            ...(trace?.mutationId ? { mutationId: trace.mutationId } : {}),
+            ...(trace?.globalSequence ? { globalSequence: trace.globalSequence } : {}),
+        };
+        this.stage({
+            primitive: "download",
+            stage: "immutable-content",
+            status: "started",
+            ...identifiers,
+            measurements: { journey: trace?.journey ?? "bootstrap", kind: artifact.kind },
+        });
         const cache = { target: null };
         const getChunk = async (manifest, index) => {
             const chunk = manifest.chunks[index];
             if (!chunk)
                 throw new Error(`content manifest has no chunk ${index}`);
+            requests += 1;
             const frame = await retryContent(() => this.wire.request({
                 type: "private.entity-content.get",
                 resource_id: resourceId,
@@ -839,12 +1117,15 @@ export class UserGroundHost {
                 part_index: index,
                 sha256: chunk.sha256,
             }, ["private.entity-content.data"]), true, retryAttempts);
-            return binaryFrameBytes(frame);
+            const bytes = binaryFrameBytes(frame);
+            downloadedBytes += bytes.byteLength;
+            return bytes;
         };
         try {
             const receipt = await downloadArtifact(artifact, {
                 sha256Hex,
                 getManifest: async () => {
+                    requests += 1;
                     const frame = await retryContent(() => this.wire.request({
                         type: "private.entity-content.get",
                         resource_id: resourceId,
@@ -852,7 +1133,9 @@ export class UserGroundHost {
                         kind: "manifest",
                         part_index: 0,
                     }, ["private.entity-content.data"]), false, retryAttempts);
-                    const candidate = JSON.parse(verifiedFrameBytes(frame).toString("utf8"));
+                    const manifestBytes = verifiedFrameBytes(frame);
+                    downloadedBytes += manifestBytes.byteLength;
+                    const candidate = JSON.parse(manifestBytes.toString("utf8"));
                     const checked = checkContentManifest(candidate, artifact.contentHash);
                     if (!checked.ok)
                         throw new Error(checked.error);
@@ -883,7 +1166,10 @@ export class UserGroundHost {
                             bytes: manifest.chunks[index]?.bytes,
                         })),
                     }, ["private.entity-content.data-batch"]), true, retryAttempts);
-                    return decodeContentWireBytes(binaryWireFrameBytes(frame), frame.content_encoding, Number(frame.bytes));
+                    requests += 1;
+                    const decoded = await decodeContentWireBytes(binaryWireFrameBytes(frame), frame.content_encoding, Number(frame.bytes));
+                    downloadedBytes += Number(frame.wire_bytes ?? frame.bytes);
+                    return decoded;
                 },
                 putChunk: async (_candidate, _manifest, index, bytes) => {
                     if (!cache.target)
@@ -902,8 +1188,35 @@ export class UserGroundHost {
                     return { local: sealed, bytes: sealed.bytes, contentHash: sealed.contentHash };
                 },
             }, artifact.kind === "file" ? { concurrency: FILE_BATCH_DOWNLOAD_CONCURRENCY } : {});
+            this.stage({
+                primitive: "download",
+                stage: "immutable-content",
+                status: "completed",
+                ...identifiers,
+                durationMs: performance.now() - started,
+                measurements: {
+                    journey: trace?.journey ?? "bootstrap",
+                    kind: artifact.kind,
+                    declaredBytes: receipt.manifest.bytes,
+                    downloadedBytes,
+                    downloadedChunks: receipt.downloadedChunks,
+                    reusedChunks: receipt.reusedChunks,
+                    requests,
+                },
+            });
             return receipt.local;
         }
+        catch (error) {
+            this.stage({
+                primitive: "download",
+                stage: "immutable-content",
+                status: "failed",
+                ...identifiers,
+                durationMs: performance.now() - started,
+                measurements: { journey: trace?.journey ?? "bootstrap", kind: artifact.kind, requests },
+            });
+            throw error;
+        }
         finally {
             await cache.target?.close();
         }
@@ -911,6 +1224,7 @@ export class UserGroundHost {
     ensureWatchers(identity, authoritativeBaselineRootIds = []) {
         if (this.closing)
             return this.watchHost.health();
+        const started = performance.now();
         const root = this.userRoot(identity);
         const wanted = new Map([[root, {
                     rootId: `user:${identity.userId}`,
@@ -935,6 +1249,18 @@ export class UserGroundHost {
         if (health.state !== "healthy" || health.contentHandles < 1) {
             throw new Error(`Watch coverage is degraded: ${health.reason ?? "no content coverage"}`);
         }
+        this.stage({
+            primitive: "watch",
+            stage: "topology-reconcile",
+            status: "completed",
+            durationMs: performance.now() - started,
+            measurements: {
+                logicalRoots: health.logicalRoots,
+                contentHandles: health.contentHandles,
+                addressHandles: health.addressHandles,
+                authoritativeBaselines: authoritativeBaselineRootIds.length,
+            },
+        });
         return health;
     }
     scheduleRescan(retryDelayMs) {
@@ -1030,7 +1356,15 @@ export class UserGroundHost {
         }
     }
     async syncLocalChanges(identity) {
+        const waitStarted = performance.now();
+        this.stage({ primitive: "detect", stage: "ground-wait", status: "started" });
         const release = await this.acquireGroundEffect();
+        this.stage({
+            primitive: "detect",
+            stage: "ground-wait",
+            status: "completed",
+            durationMs: performance.now() - waitStarted,
+        });
         try {
             await this.syncLocalChangesUnlocked(identity);
         }
@@ -1042,6 +1376,17 @@ export class UserGroundHost {
         if (!this.cloudState)
             throw new Error("cloud state is unavailable for user-ground Watch");
         const observations = this.watchHost.observations();
+        const passStarted = performance.now();
+        this.stage({
+            primitive: "detect",
+            stage: "pass",
+            status: "started",
+            measurements: {
+                roots: observations.length,
+                completeRoots: observations.filter(({ suspicion }) => suspicion.paths === null).length,
+                namedPaths: observations.reduce((count, { suspicion }) => count + (suspicion.paths?.length ?? 0), 0),
+            },
+        });
         let widenedRoots = new Set();
         if (this.namedDetect) {
             // The named lane is an optimization over the same settled evidence.
@@ -1052,7 +1397,7 @@ export class UserGroundHost {
             if (named?.handled) {
                 for (const evidence of named.evidence) {
                     const observation = observations.find((candidate) => candidate.directory === evidence.directory);
-                    this.options.onDetectScan?.({
+                    this.reportDetectScan({
                         rootId: observation?.rootId ?? evidence.directory,
                         directory: evidence.directory,
                         scope: "paths",
@@ -1070,6 +1415,17 @@ export class UserGroundHost {
                 this.watchHost.settle(observations);
                 this.applyRail?.localStateChanged();
                 this.recordRail?.localRecordsAvailable();
+                this.stage({
+                    primitive: "detect",
+                    stage: "pass",
+                    status: "completed",
+                    durationMs: performance.now() - passStarted,
+                    measurements: {
+                        lane: "named",
+                        roots: named.evidence.length,
+                        records: named.evidence.reduce((count, evidence) => count + evidence.records, 0),
+                    },
+                });
                 return;
             }
             widenedRoots = new Set(named?.widenedRoots ?? []);
@@ -1085,7 +1441,7 @@ export class UserGroundHost {
                 userRoot: this.userRoot(identity),
                 database: this.databasePath(identity),
                 cacheDir: this.cacheDir(identity),
-                onScan: this.options.onDetectScan,
+                onScan: (evidence) => this.reportDetectScan(evidence),
                 suspicions: new Map(observations.map((observation) => [observation.directory, widenedRoots.has(observation.directory)
                         ? { ...observation.suspicion, paths: null }
                         : observation.suspicion])),
@@ -1113,6 +1469,7 @@ export class UserGroundHost {
                 proposal,
             }))
             : []);
+        const recordCommitStarted = performance.now();
         commitDetectedState(this.databasePath(identity), {
             acceptedMaterializedRows,
             materializedRemovals,
@@ -1120,10 +1477,40 @@ export class UserGroundHost {
             notebookRemovals,
             proposals: detectedRecords,
         });
+        const recordCommitDuration = performance.now() - recordCommitStarted;
+        if (detectedRecords.length === 0) {
+            this.stage({
+                primitive: "record",
+                stage: "sqlite-transaction",
+                status: "completed",
+                durationMs: recordCommitDuration,
+                measurements: { records: 0 },
+            });
+        }
+        else {
+            for (const record of detectedRecords) {
+                this.stage({
+                    primitive: "record",
+                    stage: "outbox-committed",
+                    status: "completed",
+                    entityId: record.proposal.entityId,
+                    mutationId: record.mutationId,
+                    durationMs: recordCommitDuration,
+                    measurements: { records: detectedRecords.length },
+                });
+            }
+        }
         this.namedDetect?.refreshEnrollmentPolicy();
         this.watchHost.settle(observations);
         this.applyRail?.localStateChanged();
         this.recordRail?.localRecordsAvailable();
+        this.stage({
+            primitive: "detect",
+            stage: "pass",
+            status: "completed",
+            durationMs: performance.now() - passStarted,
+            measurements: { lane: "reconciliation", records: detectedRecords.length },
+        });
     }
     async publishPendingSnapshotsBeforeLookup(identity, resourceId) {
         const pending = readSnapshotPublications(this.databasePath(identity));
@@ -1145,7 +1532,7 @@ 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, publicationRootIds) {
+    async publishMaterializedSnapshot(identity, publicationRootIds, trace) {
         const state = this.cloudState;
         if (!state)
             throw new Error("cloud state is unavailable for graph publication");
@@ -1169,7 +1556,7 @@ export class UserGroundHost {
         const identical = pending.find((entry) => entry.resourceId === state.resourceId
             && entry.snapshotChecksum === checksum);
         if (identical) {
-            await this.publishPendingSnapshots(identity);
+            await this.publishPendingSnapshots(identity, trace);
             return;
         }
         if (pending.length > 0) {
@@ -1207,19 +1594,29 @@ export class UserGroundHost {
             replacementRootIds: replacement.rootIds,
             replacementRecords: replacement.records,
         });
-        await this.publishPendingSnapshots(identity);
+        await this.publishPendingSnapshots(identity, trace);
     }
-    async publishPendingSnapshots(identity) {
+    async publishPendingSnapshots(identity, trace) {
         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);
+                await this.uploadSnapshotContent(identity, pending.resourceId, pending.uploadRecords, trace);
             }
             catch (error) {
                 throw pipelineStageError("cloud upload", error);
             }
             let frame;
+            const graphCommitStarted = performance.now();
+            if (trace?.journey === "register") {
+                this.stage({
+                    primitive: "register",
+                    stage: "cloud-graph-commit",
+                    status: "started",
+                    ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+                    ...(trace.mutationId ? { mutationId: trace.mutationId } : {}),
+                });
+            }
             try {
                 frame = await this.wire.request({
                     type: "shared.mutation.submit",
@@ -1237,8 +1634,27 @@ export class UserGroundHost {
                 }, ["shared.mutation.ack"]);
             }
             catch (error) {
+                if (trace?.journey === "register") {
+                    this.stage({
+                        primitive: "register",
+                        stage: "cloud-graph-commit",
+                        status: "failed",
+                        ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+                        durationMs: performance.now() - graphCommitStarted,
+                    });
+                }
                 throw pipelineStageError("cloud graph commit", error);
             }
+            if (trace?.journey === "register") {
+                this.stage({
+                    primitive: "register",
+                    stage: "cloud-graph-commit",
+                    status: "completed",
+                    ...(trace.workspaceId ? { workspaceId: trace.workspaceId } : {}),
+                    durationMs: performance.now() - graphCommitStarted,
+                    measurements: { version: Number(frame.version) },
+                });
+            }
             this.cloudState = {
                 resourceId: pending.resourceId,
                 authorityEpoch: Number(frame.authority_epoch),