T-8L0G-gs-goal-directed-frontier

Status: planning/backlog · Impact: medium · Complexity: medium

Goal

Add goal-direction to graph_scheduler: the toward soft priority over an ordered goal list, the only_toward hard predicate, and what_blocks.

Deferred until after cutover. Not part of graph-scheduler v0.1. The dispatcher’s first real work order needs a frontier, filters and an ordering; it does not need goal-direction. This task is parked at planning/backlog so it is not pickable, and is re-promoted to open/ready once the engine takes the tick.

Today

Location	Role today
`packages/rust/graph-scheduler/src/goal.rs`	Does not exist. Not scaffolded by T-ROJC-gs-test-corpus-and-disabled-suites, which stops at the v0.1 layers
`packages/rust/graph-scheduler/src/ready.rs`	`ReadyOptions::toward` is declared by T-I3QP-gs-push-readiness-frontier but unread
`packages/rust/graph-scheduler/src/graph.rs`	`ancestors` is landed by T-JVXC-gs-dag-core; goal-direction needs no new topology query

Proposed

src/goal.rs, plus reading the toward field ReadyOptions already carries.

Item	Shape
`ReadyOptions::toward`	`Vec<NodeId>` — an ordered goal list, read here for the first time
`only_toward(goal) -> impl Fn(&ReadyNode) -> bool`	The hard case, passed as `where_fn`
`what_blocks(&Schedule, &impl StatusSource, &NodeId) -> Vec<NodeId>`	A goal’s unfinished ancestors that are not yet runnable

toward is a soft priority, not a filter. Each ready node is ranked by the earliest listed goal whose ancestors include it, with non-goal nodes last, and that key is composed ahead of the registered sorter. limit then fills goal-advancing work first and spills spare capacity to the rest of the frontier, so “one goal with leftover slots” and “a priority-ordered list of goals” are the same mechanism.

only_toward is the hard complement: drop everything that does not advance the goal. It is a predicate for where_fn rather than a registered filter, because it is a call-time focus rather than a standing policy.

Approach

Implement the goal-rank sort key over Graph::ancestors, composed ahead of the registered sorter.
Implement only_toward and what_blocks.
Land the Layer 6 fixture table from T-ROJC’s matrix as a const table in tests/goal.rs, un-ignored, and make it green.

Files to touch

Location	Kind	Change
`packages/rust/graph-scheduler/src/goal.rs`	new	`toward` ranking, `only_toward`, `what_blocks`
`packages/rust/graph-scheduler/src/ready.rs`	modify	Read `ReadyOptions::toward`
`packages/rust/graph-scheduler/src/lib.rs`	modify	Declare the module; re-export `only_toward`, `what_blocks`
`packages/rust/graph-scheduler/tests/goal.rs`	new	Layer 6 fixtures

Acceptance criteria

AC-1: toward ranks a goal’s unfinished ancestors ahead of non-goal nodes, and spare limit capacity spills to non-goal work.
AC-2: An ordered toward list tiers by goal — the earliest listed goal’s ancestors rank above the next goal’s.
AC-3: only_toward(goal) used as where_fn drops every node that does not advance the goal.
AC-4: what_blocks returns the goal’s unfinished, not-yet-runnable ancestors.
AC-5: Every row of T-ROJC’s Layer 6 fixture table passes in tests/goal.rs.

Out of scope

Pull resolution (T-0WNK-gs-pull-resolution) and the tracker (T-EJ3P-gs-stateful-tracker).
Any change to the v0.1 layers beyond reading the toward field they already declare.

Dependencies

T-BR6H-gs-priority-sorters — the goal-rank key composes ahead of the sorter that task builds.

Depends on

T-BR6H-gs-priority-sorters

← Back to Tasks