Add staging events to the TraceObserverV2

[rcannood]

This PR implements file staging event notifications for TraceObserverV2, allowing plugins to track when remote files are staged to the local work directory. This resolves #5905 by providing observers access to both the original remote file paths and their staged local paths.

Background

Issue #5905 identified a need for provenance tracking plugins (specifically nf-lamin) to access the original remote paths of input files, not just their staged local paths. Two previous attempts were made to solve this:

• Extend observer with onFileStage #5907: Added onFileStage to TraceObserver - rejected in favor of Include remote path in FileHolder #5911
• Include remote path in FileHolder #5911: Modified FileHolder to include remote paths - merged but then reverted due to concerns about cache invalidation and risk to core functionality

I met up with @bentsherman at the beginning of September. He said he wanted to have another shot at resolving this issue, and that I could reach out in a few weeks time if no progress was made.

Solution

This implementation is a simpler solution in comparison to the two previous PRs. I added this to the TraceObserverV2:

• onFileStaged(FileStagingEvent event) - Called after a file has been successfully staged from a remote location

The FileStagingEvent provides:

• source: The original remote path (e.g., s3://bucket/file.txt, https://example.com/data.csv)
• target: The staged local path in the work directory (e.g., work/.../file.txt)

Usage Example

For plugins that need to track file provenance (like nf-lamin):

class ProvenanceObserver implements TraceObserverV2 {
    
    @Override
    void onFileStaged(FileStagingEvent event) {
        // event.source = original remote path
        // event.target = staged local path
        log.info "File staged: ${event.source} -> ${event.target}"
        registerFileProvenance(event.source, event.target)
    }
}

Related Issues

• Resolves Detect when files are being staged #5905
• Supersedes Extend observer with onFileStage #5907 (rejected)
• Supersedes Include remote path in FileHolder #5911 (reverted)

[netlify]

✅ Deploy Preview for nextflow-docs-staging canceled.

Name	Link
🔨 Latest commit	b6e17d2
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/68de838084522d0007eca63e