Prefer package-ready peers when planning Skippy splits

[IvGolovach]

Summary

Skippy split planning can now account for layer-package readiness before assigning contiguous layer ranges. When peers have comparable capacity, the planner prefers nodes that already have the needed package bytes, penalizes missing or non-transferable artifacts, treats RTT as a cost instead of a hard exclusion, and preserves the existing weighted behavior when no package signals are available.

Why

Recent Skippy package work makes layer artifacts a first-class part of distributed serving. Capacity-only planning can still choose a topology that looks balanced but causes avoidable package movement, startup delay, or a failed placement when a peer cannot fetch missing artifacts.

This keeps the existing capacity balancing model, but gives the planner enough optional locality and transfer signals to choose a more realistic split topology for package-backed Skippy runs.

Diff scope

• Adds NodePlacementSignal to skippy-topology for optional cache-locality, missing-artifact, RTT, transfer-support, and availability inputs.
• Adds plan_package_aware_contiguous while keeping plan_weighted_contiguous as the no-signal compatibility path.
• Extends StagePlan with defaulted package-readiness metadata for cached bytes, missing bytes, and RTT.
• Wires the host-runtime Skippy topology adapter and local runtime planning through the package-aware planner.
• Adds focused tests for no-signal parity, cached peer preference, untransferable artifact penalties, high-RTT cost handling, extra cached peer promotion, and host-runtime adapter mapping.

Protocol / compatibility

No mesh protocol, gossip, protobuf, ALPN, or CLI contract changes are introduced.

The new StagePlan fields are additive and defaulted for deserialization. Existing callers of plan_weighted_contiguous continue to get the previous behavior. When no package placement signals are provided, the package-aware planner intentionally matches the existing weighted planner output.

Branch integrity

• Base branch: main
• Validated base SHA: 8d12c0be26fb3af4ed309fde6df65acfabff0162
• git rev-list --left-right --count origin/main...HEAD: 0 1
• Merge-base SHA: 8d12c0be26fb3af4ed309fde6df65acfabff0162
• Fast-forward safety: origin/main is an ancestor of HEAD; no divergence.

Commit integrity

• Introduced commit: 1c0c85b1c4e749cd7a06cce8b0485bcfc6c68137 Add package-aware Skippy topology planning
• One logical change: package-aware Skippy topology planning and the runtime adapter wiring needed to use it.
• Ledger: not applicable - not required for this change family.
• Version: not applicable - no release/version metadata changed.

Diff hygiene

M crates/mesh-llm-host-runtime/src/inference/skippy/topology.rs
M crates/mesh-llm-host-runtime/src/runtime/local.rs
M crates/skippy-topology/src/lib.rs
M crates/skippy-topology/src/tests.rs

• git diff --check origin/main...HEAD: PASS, no output.

Validation

Validation mode: Mode 3 - shared Skippy planning/runtime behavior. This changes topology scoring inputs and the runtime planner adapter, so local proof covers both the planner crate and the host-runtime adapter.

git diff --check origin/main...HEAD
PASS

cargo fmt --all -- --check
PASS

cargo test -p skippy-topology --lib package_aware
PASS, 5 passed

cargo test -p skippy-topology --lib
PASS, 26 passed

LLAMA_STAGE_BUILD_DIR=/Users/Funtland/Downloads/mesh-llm/.deps/llama.cpp/build-stage-abi-metal cargo test -p mesh-llm-host-runtime inference::skippy::topology --lib
PASS, 3 passed

LLAMA_STAGE_BUILD_DIR=/Users/Funtland/Downloads/mesh-llm/.deps/llama.cpp/build-stage-abi-metal cargo check -p mesh-llm-host-runtime
PASS

LLAMA_STAGE_BUILD_DIR=/Users/Funtland/Downloads/mesh-llm/.deps/llama.cpp/build-stage-abi-metal cargo check -p mesh-llm
PASS

Not run: multi-node Skippy split smoke. This local PR-ready slice is covered by planner and runtime-adapter tests; required GitHub CI should still be treated as the final merge gate after the PR is opened.

CI context confirmation

Pending - GitHub Actions cannot run until the PR is opened. No workflow files or CI context names changed.

Runtime safety

• Reviewed runtime paths: crates/skippy-topology/src/lib.rs, crates/mesh-llm-host-runtime/src/inference/skippy/topology.rs, and crates/mesh-llm-host-runtime/src/runtime/local.rs.
• No new locks, queues, background tasks, network protocols, or blocking runtime paths were added.
• The existing weighted capacity behavior is preserved when package signals are absent.
• Missing artifacts and transfer support affect placement score; they do not introduce new download or transport behavior in this PR.
• No invariant regression introduced.

Documentation integrity

Not applicable - no README, runbook, command, or user-facing CLI behavior changed.

Migration notes

Not applicable - no database or persisted-state migration changed.

Rollback plan

Rollback: revert this PR.

DB downgrade: not applicable.
Data repair: not applicable.
Operational caveats: rollback restores capacity-only Skippy topology planning.

Known residual risks

• Real multi-node package-transfer behavior still depends on callers supplying accurate placement signals. When those signals are unavailable, the planner deliberately falls back to the existing weighted behavior.

[i386]

@IvGolovach incredibly cool. Reviewing.

[i386]

Finding

• P1: package-aware placement is not wired into the live split planner. In plan_runtime_slice_topology, every live NodeSpec is still built with cached_slice_bytes: 0, then calls plan_package_aware_contiguous(&request) without placement signals. The planner immediately falls back to weighted behavior when there are no cached bytes or signals, so production split planning cannot prefer cached peers, account for RTT, or penalize missing/non-transferable artifacts. Upstream, peers missing the full package are also excluded before planning. See crates/mesh-llm-host-runtime/src/runtime/local.rs around the participant inclusion and topology request construction, plus the fallback in crates/skippy-topology/src/lib.rs. The new signal-aware adapter in crates/mesh-llm-host-runtime/src/inference/skippy/topology.rs appears to have no non-test call sites, so the PR's main behavior looks test-only/dead in the actual runtime path.

Open question

Should the live SplitParticipant carry inventory-derived cached/missing bytes plus peer.rtt_ms and peer.artifact_transfer_supported, then call plan_package_aware_contiguous_with_signals?

[i386]

After these are addressed, please merge! 👍