fix(server): absolute file:// URLs never resolve under --media-path #1612

Problem

--media-path does permit file:// reads, but only for references interpreted as relative to the root. An absolute file:// URL, the form every other tool accepts and the form scripts/bench_embeddings.py:17 generates, can never resolve. resolve_media_file_in (src/server/media_root.rs:209-226) strips the file:// prefix, strips leading separators via relative_component, then joins the remainder onto the root, so file://<abs-repo>/tests/fixtures/test_image.png under --media-path <abs-repo>/tests/fixtures is probed at <root>/Users/.../tests/fixtures/test_image.png. That does not exist, and the client is told file does not exist or cannot be opened: followed by the path it sent, naming a file that is present and readable. The path actually probed is never disclosed, so the error is undiagnosable from the outside.

The concatenation itself is deliberate llama-server b10621 compatibility, pinned by an_absolute_looking_path_is_concatenated_not_joined (src/server/media_root_tests.rs:72-92). The defect is that nothing states the rule: --help (src/cli/multimodal_compat_args.rs:199-204) says only "Directory that local file:// media URLs are resolved against", and docs/llama-server-compat.md:485 says "the request's path is resolved against the configured directory".

Verified on this checkout

Server started with --media-path "$PWD/tests/fixtures" on nvidia/llama-nemotron-embed-vl-1b-v2, then one POST /v1/embeddings per row with {"input":[{"type":"image_url","image_url":{"url":URL}}]}.

The three accepted file:// forms return a 2048-dim vector bit-identical to the data: URI form (max abs diff 0.0), so the read and decode path is healthy and only the absolute form fails. Containment still holds: file://../../etc/passwd is refused with file path is not allowed. Environment: mlxcel 0.6.0 at b2ff1eee, macOS 26.6.2 (25G83), M5 Max 128GB, --features metal,accelerate, MLX pin 9a795735.

Proposed solution

Keep the upstream concatenation as the primary resolution so b10621 compatibility and every existing containment test hold unchanged, and add an absolute-path fallback in resolve_media_file_in: when the concatenated candidate does not resolve and raw is absolute, canonicalize raw itself and accept it only if it passes the same canonical.starts_with(root) check already there. This only converts previous errors into acceptances, never the reverse, and adds no second containment path. An absolute path outside the root must surface as MediaPathError::Escape, not Unresolvable.

Then make the failure self-explaining. MediaPathError::Unresolvable is asserted only with contains (src/server/media_root_tests.rs:236-240), unlike NO_MEDIA_ROOT_MESSAGE which is pinned character for character (:246-253), so its message may carry a suffix saying paths resolve relative to --media-path. Log the probed candidate at debug rather than returning it, so the root is not disclosed to clients. State the rule in the --help text and docs/llama-server-compat.md:483-496.

Out of scope: the NoRoot wording, and the video path in src/server/media.rs. scripts/bench_embeddings.py can stay on the data: URI, which needs no allow-list, but its stale docstring at :106 and comment at :171 claim file:// is refused outright and must be corrected.

Acceptance criteria

• An absolute file:// URL naming a file inside the root is accepted by /v1/embeddings and /v1/rerank and returns a vector identical to the data: URI form for the same image. (PR fix(server): resolve absolute file:// URLs under --media-path #1620. The fix is in the shared resolver, whose sole caller serves all four routes; verified end to end on /v1/chat/completions with models/mlx/qwen2.5-vl-3b-instruct, because nvidia/llama-nemotron-embed-vl-1b-v2 is not on the host.)
• An absolute file:// URL naming a file outside the root is refused as an escape, and the existing symlink-escape and traversal tests still pass unchanged. (PR fix(server): resolve absolute file:// URLs under --media-path #1620.)
• file://test_image.png, test_image.png, and file:///test_image.png still resolve. (PR fix(server): resolve absolute file:// URLs under --media-path #1620.)
• The unresolvable error tells the operator that paths are resolved relative to --media-path, and the probed candidate appears in the server log but not in the response. (PR fix(server): resolve absolute file:// URLs under --media-path #1620, at debug level.)
• --help and docs/llama-server-compat.md state the resolution rule and show an accepted absolute and an accepted relative form. (PR fix(server): resolve absolute file:// URLs under --media-path #1620. The new divergence is also recorded on the --media-path manifest entry's checked divergence list.)
• The "Open finding" section at docs/benchmark_results/embeddings-rerank-m5max-2026-09-04.md:79-88 is corrected. (Premise corrected: that document exists only on bench/0.7.0-refresh (PR bench: refresh the 0.7.0 sweeps and fix the dtype, rotary and rope defects they exposed #1617), and the section had already been rewritten there as "Why the image cells use a data URI" with an accurate description. The remaining work was the opposite, updating it for the fix, and is commit c3a999b1e on that branch, NOT on main.)
• The change lands in the live request path used by the embeddings, rerank, chat, and responses media handlers, not in a standalone helper. (PR fix(server): resolve absolute file:// URLs under --media-path #1620, inside resolve_media_file_in.)

Verification

cargo test --release media_root
cargo clippy --all-targets -- -D warnings
cargo fmt --check

Manual, against a real checkpoint:

./target/release/mlxcel-server -m <store>/nvidia/llama-nemotron-embed-vl-1b-v2 --host 127.0.0.1 --port 18094 --media-path "$PWD/tests/fixtures" &
curl -s -X POST http://127.0.0.1:18094/v1/embeddings -H 'Content-Type: application/json' \
  -d "{\"input\":[{\"type\":\"image_url\",\"image_url\":{\"url\":\"file://$PWD/tests/fixtures/test_image.png\"}}]}"

A pass is HTTP 200 with a 2048-dim embedding equal to the one the data: URI form returns for tests/fixtures/test_image.png.

Origin

Introduced with the media confinement in #1451 (229d10e0, merged 2026-08-28). The GB10 embedding pass (benchmarks/cuda_gb10_embeddings_2026-08-26.csv) predates it by two days, which is why its image cells passed. On the 2026-09-04 M5 Max run all five image cells returned HTTP 400.