Priority ordering and sorters

Status: open/planned · Kind: component · Audience: user

Summary

• Registered sorters that order the ready frontier when it exceeds the requested N; priority_weight is the built-in default.
• Ordering is soft (contrast filters’ hard gate): get_ready returns the frontier and sorters decide which N win.
• Sub-capability of C-D2GO-readiness-scheduling.

Statement

When more nodes are ready than the caller asked for, something must choose which N. Sorters rank the frontier; the top N are returned. priority_weight sorts by a node’s weight descending, with a WeightRule::Downstream mode that bubbles the rank of everything a node unblocks back to the node. Callers register their own sorters for domain-specific ordering. Ordering is soft: a low-ranked node is deferred, not withheld.

Downstream propagation is a maximum over the node and its transitive descendants, iterated to a fixed point — not a sum. A comparable key is what propagates, and a lexicographic tuple cannot be added; it can be maximized. So a low-impact blocker of high-impact work ranks as high as the work it unblocks.

What it provides

• Schedule::sort(impl Sorter) registration and ReadyOptions::order as the call-time equivalent.
• by_key(name, rule, key_fn) — rank by any Ord key the caller extracts. This is the general surface; the comparable key never has to be a number.
• priority_weight(rule) — the numeric convenience over attrs.weight.
• Stable, deterministic ordering (ties broken by insertion order).

use graph_scheduler::{ReadyOptions, WeightRule, priority_weight};

let opts = ReadyOptions {
    limit: Some(4),
    order: Some(Box::new(priority_weight(WeightRule::Downstream))),
    ..Default::default()
};

Inputs

• Registered sorters, or a call-time order.
• For priority_weight, a per-node weight attribute; for by_key, any caller-supplied Ord key.

Outputs

• The ordered frontier; the top N after the cap.

Underlying implementation

• No code realizes this yet — the capability is planned. It lands with the crate at packages/rust/graph-scheduler/, the sorters in src/sorters.rs. Until the crate exists there is no anchor to record here.

Notes

• Soft vs. hard: sorters defer, filters (C-GUGX-eligibility-filters) exclude. Critical-path is offered as a sorter option, not a scheduling default — Buck2 exposes critical path observability-only (graph-scheduler-research). Anti-starvation (age / round-robin fairness) is a later sorter.
• First-consumer requirement (A). The SDLC adapter (T-8I15-adapt-task-next-onto-graph-scheduler) needs downstream propagation over a comparable key, not a scalar weight sum: D-Q2WR-task-pickup-order’s lift bubbles a dependent’s lexicographic tuple (priority > impact > complexity > created) to its blockers by max-to-fixed-point, and it is the default (always-on), not an opt-in option. by_key is the surface that satisfies this; see D-BPD8-graph-scheduler-api §First consumer.
• The tuple itself stays in the adapter. A domain-blind crate does not know what impact or complexity are, so SDLC supplies them as a key_fn when task next is rebased in Track C.

---

← Back to Capabilities