Unified cross-region transfer budget (10GB) (#3627)

- Merge `mirror_fs.py` into `marin_fs.py` — single file for all
cross-region filesystem logic
- Replace the old 100MB per-file `CrossRegionReadError` and per-instance
`MirrorCopyLimitExceeded` with a shared, thread-safe `TransferBudget`
(10GB process-global limit)
- Both `CrossRegionGuardedFS` (direct reads) and `MirrorFileSystem`
(mirror copies) draw from the same budget
- Remove `_is_gcs` field from `CrossRegionGuardedFS` — redundant since
entry points already only wrap GCS

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Russell Power <rjpower@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

experiments/AGENTS.md

@@ -21,7 +21,6 @@ Start with `/AGENTS.md`; this file adds experiment-specific guidance.
 - Read behavior: check local `marin_prefix()` first; if missing, scan other Marin regional buckets, copy to local once, then serve locally.
 - Copying uses a distributed lock so concurrent workers do not duplicate the same transfer.
 - Write behavior: writes go directly to the local prefix.
-- There is a cumulative copy budget (`MIRROR_COPY_LIMIT_BYTES`, default 10 GB) that can raise `MirrorCopyLimitExceeded`.
-- Separate from `mirror://`, direct cross-region GCS reads are guarded at 100 MB in `CrossRegionGuardedFS`.
+- Both `mirror://` copies and direct cross-region GCS reads share a single process-global `TransferBudget` (default 10 GB) that raises `TransferBudgetExceeded` when exhausted.
 
-Implementation references: `lib/iris/src/iris/mirror_fs.py`, `lib/iris/src/iris/marin_fs.py`, and `lib/marin/src/marin/execution/executor.py`.
+Implementation references: `lib/iris/src/iris/marin_fs.py` and `lib/marin/src/marin/execution/executor.py`.