@amalgm/shell 0.1.131 → 0.1.133

package/dist/transfer-instrumentation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-leg accounting for one content transfer.
+ *
+ * Every instrumented operation lands its wall time in exactly one named leg.
+ * Legs sum busy time across concurrent operations, so under a wide window
+ * their total may exceed the transfer's wall clock; `idleMs` is the opposite
+ * fact — wall time in which zero instrumented operations were in flight — so
+ * a transfer's ledger reads as legs (where work went) plus idle (where
+ * nothing went). Externally measured durations (a gateway acknowledgement's
+ * own timings) fold in without in-flight tracking: they decompose a timed
+ * leg, they do not extend it.
+ */
+export declare class TransferLegs {
+    private readonly totals;
+    private inFlight;
+    private quietSince;
+    private idleMs;
+    /** Fold an externally measured duration into a leg. Absent or non-positive
+     * values contribute nothing, so wire frames may omit their timings. */
+    add(leg: string, ms: number): void;
+    time<T>(leg: string, work: () => Promise<T>): Promise<T>;
+    timeSync<T>(leg: string, work: () => T): T;
+    /** Rounded per-leg totals plus `idleMs` through this moment, ready to
+     * spread into stage measurements. */
+    report(): Record<string, number>;
+    private enter;
+    private exit;
+}

package/dist/transfer-instrumentation.js

@@ -0,0 +1,68 @@
+/**
+ * Per-leg accounting for one content transfer.
+ *
+ * Every instrumented operation lands its wall time in exactly one named leg.
+ * Legs sum busy time across concurrent operations, so under a wide window
+ * their total may exceed the transfer's wall clock; `idleMs` is the opposite
+ * fact — wall time in which zero instrumented operations were in flight — so
+ * a transfer's ledger reads as legs (where work went) plus idle (where
+ * nothing went). Externally measured durations (a gateway acknowledgement's
+ * own timings) fold in without in-flight tracking: they decompose a timed
+ * leg, they do not extend it.
+ */
+export class TransferLegs {
+    totals = new Map();
+    inFlight = 0;
+    quietSince = performance.now();
+    idleMs = 0;
+    /** Fold an externally measured duration into a leg. Absent or non-positive
+     * values contribute nothing, so wire frames may omit their timings. */
+    add(leg, ms) {
+        if (!Number.isFinite(ms) || ms <= 0)
+            return;
+        this.totals.set(leg, (this.totals.get(leg) ?? 0) + ms);
+    }
+    async time(leg, work) {
+        const startedAt = this.enter();
+        try {
+            return await work();
+        }
+        finally {
+            this.exit(leg, startedAt);
+        }
+    }
+    timeSync(leg, work) {
+        const startedAt = this.enter();
+        try {
+            return work();
+        }
+        finally {
+            this.exit(leg, startedAt);
+        }
+    }
+    /** Rounded per-leg totals plus `idleMs` through this moment, ready to
+     * spread into stage measurements. */
+    report() {
+        const now = performance.now();
+        const trailingIdle = this.inFlight === 0 ? now - this.quietSince : 0;
+        return {
+            ...Object.fromEntries([...this.totals].map(([leg, ms]) => [leg, Math.round(ms)])),
+            idleMs: Math.round(this.idleMs + trailingIdle),
+        };
+    }
+    enter() {
+        const now = performance.now();
+        if (this.inFlight === 0)
+            this.idleMs += now - this.quietSince;
+        this.inFlight += 1;
+        return now;
+    }
+    exit(leg, startedAt) {
+        const now = performance.now();
+        this.add(leg, now - startedAt);
+        this.inFlight -= 1;
+        if (this.inFlight === 0)
+            this.quietSince = now;
+    }
+}
+//# sourceMappingURL=transfer-instrumentation.js.map

package/dist/transfer-instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-instrumentation.js","sourceRoot":"","sources":["../src/transfer-instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,YAAY;IACN,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,QAAQ,GAAG,CAAC,CAAC;IACb,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAC/B,MAAM,GAAG,CAAC,CAAC;IAEnB;2EACuE;IACvE,GAAG,CAAC,GAAW,EAAE,EAAU;QACzB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC;YAAE,OAAO;QAC5C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,GAAW,EAAE,IAAsB;QAC/C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,QAAQ,CAAI,GAAW,EAAE,IAAa;QACpC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED;yCACqC;IACrC,MAAM;QACJ,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,OAAO;YACL,GAAG,MAAM,CAAC,WAAW,CACnB,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAC3D;YACD,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC;SAC/C,CAAC;IACJ,CAAC;IAEO,KAAK;QACX,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC;YAAE,IAAI,CAAC,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;QAC9D,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnB,OAAO,GAAG,CAAC;IACb,CAAC;IAEO,IAAI,CAAC,GAAW,EAAE,SAAiB;QACzC,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,SAAS,CAAC,CAAC;QAC/B,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnB,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC;YAAE,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACjD,CAAC;CACF"}

package/dist/user-ground-host.d.ts

@@ -221,7 +221,9 @@ export declare class UserGroundHost {
     /** One self-contained cargo segment on the wire: declared artifacts in
      * header order, their bytes concatenated behind them, one verified round
      * trip. Returns the authority's sealed hashes for the stream law to
-     * prove coverage. */
+     * prove coverage. The acknowledgement carries the gateway's own leg
+     * timings — verification, storage, sealing — which fold into the ledger
+     * as a decomposition of this round trip's `wireMs`. */
     private putCargo;
     private uploadSnapshotContent;
     /** Download a set of immutable artifacts straight from content storage.

package/dist/user-ground-host.js

@@ -15,6 +15,7 @@ import { ContentCacheDownloadSet, captureContentFile, hasSealedContent, hashCont
 import { StagedContentSet, addStagingEvidenceDir, clearAddStagingEvidence, } from "./workspace-add-staging.js";
 import { DirectContentPlane } from "./content-direct.js";
 import { encodeContentWireBytes } from "./content-wire-codec.js";
+import { TransferLegs } from "./transfer-instrumentation.js";
 import { exactTextReplay, planGroundDetection, reconcileGroundUUIDs, } from "./detection/portable.js";
 import { AcceptedInboxResultIndex } from "./detection/accepted-result.js";
 import { sameNotebookBasisRow } from "./detection/notebook-basis.js";
@@ -1391,17 +1392,22 @@ export class UserGroundHost {
     /** One self-contained cargo segment on the wire: declared artifacts in
      * header order, their bytes concatenated behind them, one verified round
      * trip. Returns the authority's sealed hashes for the stream law to
-     * prove coverage. */
-    async putCargo(resourceId, artifacts, payload) {
-        const encoded = await encodeContentWireBytes(payload);
-        const frame = await retryContent(() => this.wire.requestBinary({
+     * prove coverage. The acknowledgement carries the gateway's own leg
+     * timings — verification, storage, sealing — which fold into the ledger
+     * as a decomposition of this round trip's `wireMs`. */
+    async putCargo(resourceId, artifacts, payload, legs) {
+        const encoded = await legs.time("encodeMs", () => encodeContentWireBytes(payload));
+        const frame = await legs.time("wireMs", () => retryContent(() => this.wire.requestBinary({
             type: "private.entity-content.put-cargo",
             resource_id: resourceId,
             artifacts,
             bytes: payload.byteLength,
             wire_bytes: encoded.bytes.byteLength,
             ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
-        }, encoded.bytes, ["private.entity-content.stored-cargo"]));
+        }, encoded.bytes, ["private.entity-content.stored-cargo"])));
+        legs.add("gatewayVerifyMs", Number(frame.verify_ms));
+        legs.add("gatewayStoreMs", Number(frame.store_ms));
+        legs.add("gatewaySealMs", Number(frame.seal_ms));
         return {
             sealed: Array.isArray(frame.sealed) ? frame.sealed.map(String) : [],
             wireBytes: encoded.bytes.byteLength,
@@ -1417,9 +1423,12 @@ export class UserGroundHost {
             }
         }
         const started = performance.now();
+        const legs = new TransferLegs();
+        const timedSha256Hex = (input) => legs.timeSync("hashMs", () => sha256Hex(input));
         let uploadedChunks = 0;
         let reusedChunks = 0;
         let uploadedBytes = 0;
+        let loadedBytes = 0;
         let inventoryRequests = 0;
         const identifiers = {
             ...(trace?.workspaceId ? { workspaceId: trace.workspaceId } : {}),
@@ -1440,16 +1449,16 @@ export class UserGroundHost {
         // 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 alreadySealed = await legs.time("planMs", () => 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));
+        const rows = legs.timeSync("planMs", () => 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 sources = legs.timeSync("planMs", () => unsealed.map(({ artifact, uuid }) => {
             const cached = contentCacheFile(cache, artifact.contentHash);
             const fromCache = existsSync(cached);
             const row = rows.get(uuid);
@@ -1489,7 +1498,7 @@ export class UserGroundHost {
                 ...(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:
@@ -1513,10 +1522,11 @@ export class UserGroundHost {
             const loaded = new Array(segment.items.length);
             await boundedForEach(segment.items.map((item, index) => ({ source: item.source, index })), CARGO_SEGMENT_LOAD_CONCURRENCY, async ({ source, index }) => {
                 try {
-                    const bytes = source.linkTarget ?? await readFile(source.file);
+                    const bytes = source.linkTarget ?? await legs.time("loadMs", () => readFile(source.file));
+                    loadedBytes += bytes.byteLength;
                     loaded[index] = {
                         bytes,
-                        manifest: deriveUploadManifest(source.artifact, bytes, sha256Hex),
+                        manifest: deriveUploadManifest(source.artifact, bytes, timedSha256Hex),
                     };
                 }
                 catch (error) {
@@ -1529,7 +1539,7 @@ export class UserGroundHost {
                 content_hash: segment.items[index].contentHash,
                 bytes: item.manifest.bytes,
                 chunks: item.manifest.chunks.map((chunk) => ({ sha256: chunk.sha256, bytes: chunk.bytes })),
-            })), Buffer.concat(loaded.map((item) => item.bytes)));
+            })), Buffer.concat(loaded.map((item) => item.bytes)), legs);
             for (const item of loaded)
                 uploadedChunks += item.manifest.chunks.length;
             uploadedBytes += wireBytes;
@@ -1544,7 +1554,7 @@ export class UserGroundHost {
                 const chunk = manifest.chunks[index];
                 if (!chunk)
                     throw new Error(`content manifest has no chunk ${index}`);
-                await retryContent(() => this.wire.requestBinary({
+                await legs.time("wireMs", () => retryContent(() => this.wire.requestBinary({
                     type: "private.entity-content.put",
                     resource_id: resourceId,
                     content_hash: artifact.contentHash,
@@ -1553,31 +1563,32 @@ export class UserGroundHost {
                     part_count: manifest.chunks.length,
                     sha256: chunk.sha256,
                     bytes: chunk.bytes,
-                }, bytes, ["private.entity-content.stored"]));
+                }, bytes, ["private.entity-content.stored"])));
                 uploadedBytes += bytes.byteLength;
             };
             try {
                 const receipt = await uploadArtifact(artifact, {
                     bytes: fileBytes,
                     ...(knownManifest ? { manifest: knownManifest, manifestVerified: true } : {}),
-                    verify: async (contentHash) => await hashContentFile(file) === contentHash,
+                    verify: async (contentHash) => await legs.time("verifyMs", () => hashContentFile(file)) === contentHash,
                     read: async (offset, bytes) => {
                         sourceFile.handle ??= open(file, "r");
                         const handle = await sourceFile.handle;
                         const buffer = Buffer.allocUnsafe(bytes);
-                        const { bytesRead } = await handle.read(buffer, 0, bytes, offset);
+                        const { bytesRead } = await legs.time("loadMs", () => handle.read(buffer, 0, bytes, offset));
+                        loadedBytes += bytesRead;
                         return buffer.subarray(0, bytesRead);
                     },
                 }, {
-                    sha256Hex,
+                    sha256Hex: timedSha256Hex,
                     missingChunks: async (_candidate, manifest) => {
                         inventoryRequests += 1;
-                        const frame = await retryContent(() => this.wire.request({
+                        const frame = await legs.time("inventoryMs", () => retryContent(() => this.wire.request({
                             type: "private.entity-content.inventory",
                             resource_id: resourceId,
                             content_hash: artifact.contentHash,
                             chunks: manifest.chunks,
-                        }, ["private.entity-content.inventory-result"]));
+                        }, ["private.entity-content.inventory-result"])));
                         manifestPresent = frame.complete === true;
                         if (!Array.isArray(frame.missing)) {
                             throw new Error("content authority returned an invalid inventory");
@@ -1586,8 +1597,8 @@ export class UserGroundHost {
                     },
                     putChunk: async (_candidate, manifest, index, bytes) => putChunk(manifest, index, bytes),
                     putChunkBatch: async (_candidate, manifest, indexes, bytes) => {
-                        const encoded = await encodeContentWireBytes(bytes);
-                        await retryContent(() => this.wire.requestBinary({
+                        const encoded = await legs.time("encodeMs", () => encodeContentWireBytes(bytes));
+                        await legs.time("wireMs", () => retryContent(() => this.wire.requestBinary({
                             type: "private.entity-content.put-batch",
                             resource_id: resourceId,
                             content_hash: artifact.contentHash,
@@ -1600,14 +1611,14 @@ export class UserGroundHost {
                             bytes: bytes.byteLength,
                             wire_bytes: encoded.bytes.byteLength,
                             ...(encoded.encoding ? { content_encoding: encoded.encoding } : {}),
-                        }, encoded.bytes, ["private.entity-content.stored-batch"]));
+                        }, encoded.bytes, ["private.entity-content.stored-batch"])));
                         uploadedBytes += encoded.bytes.byteLength;
                     },
                     putManifest: async (_candidate, manifest) => {
                         if (manifestPresent)
                             return;
                         const bytes = Buffer.from(stableJson(manifest), "utf8");
-                        await retryContent(() => this.wire.requestBinary({
+                        await legs.time("wireMs", () => retryContent(() => this.wire.requestBinary({
                             type: "private.entity-content.put",
                             resource_id: resourceId,
                             content_hash: artifact.contentHash,
@@ -1616,7 +1627,7 @@ export class UserGroundHost {
                             part_count: manifest.chunks.length,
                             sha256: sha256Hex(bytes),
                             bytes: bytes.length,
-                        }, bytes, ["private.entity-content.stored"]));
+                        }, bytes, ["private.entity-content.stored"])));
                         uploadedBytes += bytes.byteLength;
                     },
                 });
@@ -1653,11 +1664,27 @@ export class UserGroundHost {
                     artifacts: byHash.size,
                     reusedArtifacts: byHash.size - sources.length,
                     declaredBytes: sources.reduce((total, source) => total + source.bytes, 0),
+                    // The same declared source bytes split by rail: whole small
+                    // artifacts ride shared cargo segments, larger ones ride
+                    // per-artifact chunk transfer. Any change to either rail's shape
+                    // is sized from a production trace by these four numbers.
+                    cargoArtifacts: small.length,
+                    cargoBytes: small.reduce((total, source) => total + source.bytes, 0),
+                    largeArtifacts: large.length,
+                    largeBytes: large.reduce((total, source) => total + source.bytes, 0),
                     uploadedBytes,
+                    loadedBytes,
                     uploadedChunks,
                     reusedChunks,
                     inventoryRequests,
                     cargoSegments,
+                    // Where this upload's time went, leg by leg: plan (seal inventory
+                    // + ground rows + source stats), load (source reads), hash, verify
+                    // (fused re-read + hash of a hinted manifest's source), encode
+                    // (compression), wire (data round trips, whose gateway share the
+                    // acknowledgement timings decompose), inventory round trips, and
+                    // idle — wall time with nothing in flight.
+                    ...legs.report(),
                 },
             });
         }
@@ -1668,7 +1695,7 @@ export class UserGroundHost {
                 status: "failed",
                 ...identifiers,
                 durationMs: performance.now() - started,
-                measurements: { journey: trace?.journey ?? "bootstrap" },
+                measurements: { journey: trace?.journey ?? "bootstrap", ...legs.report() },
             });
             throw error;
         }
@@ -1683,12 +1710,13 @@ export class UserGroundHost {
         const sole = unique.size === 1 ? [...unique.values()][0]?.artifact : undefined;
         const started = performance.now();
         const planeBefore = this.direct.metrics();
+        const legs = new TransferLegs();
+        const timedSha256Hex = (input) => legs.timeSync("hashMs", () => sha256Hex(input));
         let declaredBytes = 0;
         let downloadedBytes = 0;
         let downloadedChunks = 0;
         let reusedChunks = 0;
         let requests = 0;
-        let cacheWriteMs = 0;
         let stagedArtifacts = 0;
         const entityId = trace?.entityId ?? sole?.entityId;
         const identifiers = {
@@ -1724,19 +1752,19 @@ export class UserGroundHost {
         // for a fresh ref every attempt.
         const fetchObject = async (object) => {
             requests += 1;
-            const bytes = await retryContent(() => this.direct.fetchObject(resourceId, object), true, retryAttempts);
+            const bytes = await legs.time("fetchMs", () => retryContent(() => this.direct.fetchObject(resourceId, object), true, retryAttempts));
             downloadedBytes += bytes.byteLength;
             return bytes;
         };
         try {
             const receipts = await downloadAllArtifacts([...unique.values()].map((want) => want.artifact), {
-                sha256Hex,
+                sha256Hex: timedSha256Hex,
                 getManifest: async (artifact) => {
                     // The record's plan or this machine's own manifest cache already
                     // proves chunk identity; downloaded bytes are still hash-verified,
                     // so a stale local manifest can only fail loudly, never corrupt.
-                    const local = unique.get(artifact.contentHash)?.manifest
-                        ?? readCachedManifest(cacheDir, artifact.contentHash);
+                    const local = legs.timeSync("planMs", () => unique.get(artifact.contentHash)?.manifest
+                        ?? readCachedManifest(cacheDir, artifact.contentHash));
                     const manifest = local ?? await (async () => {
                         const bytes = await fetchObject({ kind: "manifest", sha256: artifact.contentHash });
                         const checked = checkContentManifest(JSON.parse(bytes.toString("utf8")), artifact.contentHash);
@@ -1748,32 +1776,28 @@ export class UserGroundHost {
                     // destination — except content this machine already holds sealed,
                     // which stays on the cache rail so a warm re-Add remains a local
                     // clone instead of a fresh download.
-                    const stagedPaths = stagedSet && staged?.destinations.get(artifact.contentHash);
-                    if (stagedPaths && !hasSealedContent(cacheDir, artifact.contentHash, manifest.bytes)) {
-                        stagedArtifacts += 1;
-                        targets.set(artifact.contentHash, stagedSet.target(artifact, manifest, stagedPaths));
-                    }
-                    else {
-                        targets.set(artifact.contentHash, downloads.target(artifact, manifest));
-                    }
+                    legs.timeSync("planMs", () => {
+                        const stagedPaths = stagedSet && staged?.destinations.get(artifact.contentHash);
+                        if (stagedPaths && !hasSealedContent(cacheDir, artifact.contentHash, manifest.bytes)) {
+                            stagedArtifacts += 1;
+                            targets.set(artifact.contentHash, stagedSet.target(artifact, manifest, stagedPaths));
+                        }
+                        else {
+                            targets.set(artifact.contentHash, downloads.target(artifact, manifest));
+                        }
+                    });
                     return manifest;
                 },
-                hasChunk: async (artifact, _manifest, index) => target(artifact).hasChunk(index),
+                hasChunk: async (artifact, _manifest, index) => legs.time("reuseMs", () => target(artifact).hasChunk(index)),
                 getChunk: async (_artifact, manifest, index) => {
                     const chunk = manifest.chunks[index];
                     if (!chunk)
                         throw new Error(`content manifest has no chunk ${index}`);
                     return fetchObject({ kind: "block", sha256: chunk.sha256 });
                 },
-                putChunk: async (artifact, _manifest, index, bytes) => {
-                    const writeStarted = performance.now();
-                    await target(artifact).putChunk(index, bytes);
-                    cacheWriteMs += performance.now() - writeStarted;
-                },
+                putChunk: async (artifact, _manifest, index, bytes) => legs.time("writeMs", () => target(artifact).putChunk(index, bytes)),
                 sealArtifact: async (artifact) => {
-                    const sealStarted = performance.now();
-                    const sealed = await target(artifact).seal();
-                    cacheWriteMs += performance.now() - sealStarted;
+                    const sealed = await legs.time("sealMs", () => target(artifact).seal());
                     return { local: sealed, bytes: sealed.bytes, contentHash: sealed.contentHash };
                 },
             }, {
@@ -1803,12 +1827,17 @@ export class UserGroundHost {
                     reusedChunks,
                     // `requests` is logical object reads; the plane deltas below are
                     // the physical facts — actual storage GETs, sealed bytes on the
-                    // wire, refs round-trips, decrypt and local-write CPU.
-                    // `cacheWriteMs` is all local placement time, cache and staged
-                    // rails alike; `stagedArtifacts` counts single-write placements.
+                    // wire, refs round-trips, decrypt CPU. The legs place local time:
+                    // plan (manifest cache + routing), fetch (storage waits, whose
+                    // decrypt share the plane delta names), hash (chunk verification),
+                    // reuse (retained-chunk re-proof), write (chunk placement), seal
+                    // (whole-file proof + durability), and idle — wall time with
+                    // nothing in flight. The staged rail decomposes its own write and
+                    // seal internals below; `stagedArtifacts` counts its placements.
                     requests,
                     ...physicalPlaneDelta(planeBefore, this.direct.metrics()),
-                    cacheWriteMs: Math.round(cacheWriteMs),
+                    ...legs.report(),
+                    ...(stagedSet ? stagedSet.report() : {}),
                     ...(stagedArtifacts > 0 ? { stagedArtifacts } : {}),
                 },
             });
@@ -1826,6 +1855,7 @@ export class UserGroundHost {
                     artifacts: unique.size,
                     ...(sole ? { kind: sole.kind } : {}),
                     requests,
+                    ...legs.report(),
                 },
             });
             throw error;
@@ -2425,7 +2455,8 @@ export class UserGroundHost {
         if (pages.length === 0)
             return;
         const started = performance.now();
-        const sealed = await this.sealedContentHashes(resourceId, pages.map((page) => page.sha256));
+        const legs = new TransferLegs();
+        const sealed = await legs.time("planMs", () => this.sealedContentHashes(resourceId, pages.map((page) => page.sha256)));
         const unsealed = pages
             .filter((page) => !sealed.has(page.sha256))
             .map((page) => ({ contentHash: page.sha256, bytes: page.bytes.byteLength, page }));
@@ -2439,7 +2470,7 @@ export class UserGroundHost {
                     content_hash: item.contentHash,
                     bytes: item.bytes,
                     chunks: [{ sha256: item.contentHash, bytes: item.bytes }],
-                })), Buffer.concat(segment.items.map((item) => item.page.bytes)));
+                })), Buffer.concat(segment.items.map((item) => item.page.bytes)), legs);
                 uploadedBytes += wireBytes;
                 return stored;
             },
@@ -2455,6 +2486,7 @@ export class UserGroundHost {
                 pages: pages.length,
                 uploadedPages: unsealed.length,
                 uploadedBytes,
+                ...legs.report(),
             },
         });
     }