plan
Returns a Draft that minimises coordinationCost by applying the E-2 rewrite rules to a fixpoint and then consolidating independent embroideries.
Round-count reduction (G4): consolidateEmbroideries (included in optimize) fuses independent DraftStage.Embroider nodes at the same dependency level into a single DraftStage.BatchedEmbroider. On a multi-coordination Draft, this drives coordinationCost(plan(draft)).rounds to the coordination DAG depth — a measurable cut vs. the unplanned rounds = K (one per Embroider node).
The returned Draft is always semantically equivalent to the receiver under isEquivalentTo — the rewrite never changes the convergent result.
Parameters
reserved for future stats-aware reordering (e.g. ordering filters by ascending selectivity). Currently unused — all rewrites are structurally determined by CoordinationKind tags. Use coordinationCost to measure the plan's quality after calling plan.
See also
Samples
val src = OpId("source.docs")
val mapScore = OpId("map.score")
val filterThreshold = OpId("filter.above-threshold")
val embroider = OpId("embroider.rank")
// Programmer places embroider early (before the filter).
val unplanned: Draft<ByteArray> = Warp.shuttle(src)
.map(mapScore)
.embroider(embroider)
.filter(filterThreshold)
// Build stats: 1 000 source docs, 50 pass the filter.
var stats = WarpStats.empty()
for (i in 1..1_000) stats = stats.piece(stats.observe(src, "doc_$i"))
for (i in 1..50) stats = stats.piece(stats.observe(filterThreshold, "doc_${i * 20}"))
// Unplanned: embroider before filter → full source cardinality.
val unplannedCost = unplanned.coordinationCost(stats)
check(unplannedCost.rounds == 1)
check(unplannedCost.coordinatedVolume >= 900L) { "should see ~1000 docs" }
// Planned: embroider deferred past filter → only ~50 docs reach consensus.
val planned = unplanned.plan(stats)
val plannedCost = planned.coordinationCost(stats)
check(plannedCost.rounds == 1)
check(plannedCost.coordinatedVolume < 100L) { "should see only ~50 docs after filter" }
check(plannedCost < unplannedCost)
check(unplanned.isEquivalentTo(planned)) { "plan must preserve equivalence" }