crawl seed --max-tier 1 reads the whole rank table and emits nothing #135

$ ccrawl crawl seed --max-tier 1 -n 5
[still running after five minutes, nothing on stdout]

ccrawl crawl seed -n 3 answers in one second. --max-tier 1 streams the entire 262 million host rank table and emits zero seeds, so -n never fires and nothing stops it early.

Why

ccrawl.CrawlTier puts a host in tier 1 only when harmonicPos <= 100_000 && changeRate > 0.8. crawl seed has ranks and no measured change rates, so cli/crawl_cmd.go:83 passes 0.5 for every host:

// Use change_rate=0.5 as conservative default for tier assignment.
// Tier 1 requires change_rate>0.8, so most hosts land in tier 2 to 5.
tier := ccrawl.CrawlTier(r.HarmonicPos, 0.5)

Not "most". Every one. Tier 1 is unreachable from this command by construction, so --max-tier 1 is a filter that matches nothing, and the only way to find that out is to wait for a full table scan.

The docs disagree with each other

The recrawl guide has it right:

One thing worth knowing about the tier column here: crawl seed has ranks but no measured change rates, so it assumes 0.5 for every host.
Tier 1 needs a change rate above 0.8, so nothing seeded this way lands in tier 1.

The CLI reference does not:

• line 704: "Use --max-tier to restrict to high-priority hosts (tier 1 = top 100 K by harmonic rank, tier 5 = all)."
• line 716: "Skip hosts with tier higher than this (1-5, default 5 = all)"

And the flag help itself says 1=top 100K only, which is the thing it cannot do.

What to do

Refuse it up front rather than after a scan:

$ ccrawl crawl seed --max-tier 1
seeds carry no measured change rate, so no host reaches tier 1; use --max-tier 2 for the top million,
or feed real change rates in with ccrawl sched diff

Keeping one definition of a tier matters more than making --max-tier 1 mean something here. If crawl seed computed tiers from rank alone it would report a different tier than sched assign does for the same host, which is a worse bug than the one being fixed.

Then correct the two reference lines and the flag help to say what the guide says.

Done when

• --max-tier 1 fails immediately with exit 2 instead of scanning the table
• --max-tier 2 still works and still stops on -n, measured against the live web graph
• the reference and the flag help say the same thing the recrawl guide says