Function shard_esp_cap

crates/kernel/src/shard.rs:1579–1621

Like [`shard_esp`] but sized to a per-shard Zisk **cycle** budget (`max_cycles`) rather than a fixed shard count: grows `N` until the heaviest splittable shard fits the budget (see [`partition_for_cycle_cap`]). Use [`cycle_cap_for_ram`] to derive `max_cycles` from a host-RAM target.

(
  esp_path: &str,
  max_cycles: u64,
  balance: f64,
  parallelism: usize,
  out_path: Option<&str>,
)

  // partition can drive max-shard heartbeats below it. When the heaviest shard
  // is pinned at this floor, adding more shards only worsens imbalance — a
  // signal to stop raising the shard count or to split the block.
  let max_block_hb =
    profile.blocks().iter().map(|b| b.heartbeats).max().unwrap_or(0);
  let max_shard_hb =
    manifest.shards.iter().map(|s| s.heartbeats).max().unwrap_or(0);
  let floored =
    num_shards > 1 && max_shard_hb <= max_block_hb.saturating_mul(11) / 10;
  let note = if floored {
    "  [balance floored by largest atomic block — more shards won't help]"
  } else {
    ""
  };
  Ok(format!(
    "blocks={} delta_edges={} nets={}\n{}\n{}\nlargest_block_hb={}{}",
    profile.num_blocks(),
    profile.num_edges(),
    h.num_nets(),
    manifest.summary(),
    prove_report(&profile, &shard_of, &manifest, parallelism),
    max_block_hb,
    note,
  ))
}

/// Like [`shard_esp`] but sized to a per-shard Zisk **cycle** budget
/// (`max_cycles`) rather than a fixed shard count: grows `N` until the heaviest
/// splittable shard fits the budget (see [`partition_for_cycle_cap`]). Use
/// [`cycle_cap_for_ram`] to derive `max_cycles` from a host-RAM target.
pub fn shard_esp_cap(
  esp_path: &str,
  max_cycles: u64,
  balance: f64,
  parallelism: usize,
  out_path: Option<&str>,
) -> Result<String, String> {
  let bytes =
    std::fs::read(esp_path).map_err(|e| format!("read {esp_path}: {e}"))?;
  let profile = BlockProfile::from_bytes(&bytes)
    .map_err(|e| format!("parse {esp_path}: {e}"))?;
  let plan = partition_for_cycle_cap(&profile, max_cycles, balance);
  let mut manifest =
    ShardManifest::build(&profile, &plan.shard_of, plan.num_shards)
      .with_tree(plan.tree);
  for shard in &mut manifest.shards {
    shard.assumption_root =
      ixon::merkle::merkle_root_canonical(&shard.foreign_blocks);