### 🟡 Changes recommended

[MikeGrier]

🟡 Changes recommended

Moderate documentation inconsistencies and stale topology-contract references must be corrected.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds planning documentation for the future topology-planner component and registers it in workspace planning.

Changes:

• Defines component scope and architecture.
• Records design decisions and requirements.
• Adds milestones and open-work tracking.
• Updates the workspace planning tracker.

File summaries

File	Summary
PLANS.md	Registers the planned component.
crates/topology-planner/DESIGN-NOTES.md	Records planner architecture and decisions.
crates/topology-planner/COMPONENT.md	Defines scope and component boundaries.
crates/topology-planner/CHECKLIST.md	Tracks requirements, milestones, and open work.

Review details

Suppressed comments (5)

PLANS.md:22

• The new directory is a source-component because it contains COMPONENT.md, but it does not add the required component-local PLANS.md. The repository's planning convention says each source-component keeps its own tracker; the root row alone does not provide that file. Add crates/topology-planner/PLANS.md (and track it from the root as appropriate) so this component's checklist has the same lifecycle metadata as the other components.

| [crates/topology-planner/CHECKLIST.md](crates/topology-planner/CHECKLIST.md) | in progress | **Planned, not built** -- the directory holds a plan and no code, and becomes a crate when M2 begins. Owns the mapping from a stated **goal** plus an abstracted idealized machine description to a set of execution domains: which processors host a domain, where each thread pins, which memory node it allocates from, what channel connects each pair, and where each channel's buffer lives. Filed because that mapping was **unowned**: [CHECKLIST-io-domains.md](CHECKLIST-io-domains.md) M32 lists the contracts "the runtime cannot be written without" and all of them concern the queue, while M33+.1 opens with "one pinned thread, its `IoRing`, its node-local registered pool, its shard" -- presupposing a plan nothing computed. Separate from `windows-topology-sys` because that crate states **facts** and this one applies **policy**; fusing them is what produced `outermost_partitioning_cache`, a policy answer sitting in the facts crate that three consumers then re-derived differently (SH-16.9). M1 was a *requirements* milestone -- it states what the topology must answer, and it fed the locality-model session, which has since concluded as `D-13`..`D-21`. **The component was deferred past PR #56 by direction**, contributing only planning documents there; #56 then closed unmerged on 2026-09-15 and its content is landing in peeled pieces instead, so the component is still unlanded and goes in its own pull request. Per `D-21` the topology reshape lands without it, since `windows-topology-sys` publishes a refined view of what the platform publishes and an adapter absorbs the rest. M2+ and M3+ are parked on that session concluding, and are additionally **awaiting a re-cut**: EP-D-4 and EP-D-5 re-scoped the component into four parts (`topology-model` holding the abstract machine description, the planner's traits and the plan type; `topology-planner`; an inward Windows adapter; an outward realizer), and only M1 has been reconciled with that. EP-1.1 is done and already earned its keep: checking the shard-set query against the model found `Processor::capacity` using `0` as both a valid efficiency class and a "not known" sentinel, which collide on every non-hybrid machine (filed as SH-16.12). | [crates/topology-planner/DESIGN-NOTES.md](crates/topology-planner/DESIGN-NOTES.md), [design-sessions/DESIGN-SESSION-2026-09-02-cache-locality-model.md](design-sessions/DESIGN-SESSION-2026-09-02-cache-locality-model.md) |

crates/topology-planner/CHECKLIST.md:35

• This status row is inconsistent with the checklist below: M1 contains three checked items (EP-1.1 through EP-1.3) and two unchecked items (EP-1.4 and EP-1.5), not four done and one open. Please make the summary match the actual checklist state, or check off the fourth item only if its action is genuinely complete.

| M1 the input contract | 4 done, 1 open | `EP-1.5`'s coverage half, which wants a settled model |

crates/topology-planner/CHECKLIST.md:64

• This checklist leaves a completed item as a long historical record, including the investigation, correction history, and cross-component handoff. The repository's checklist convention is action-only: once EP-1.1 is complete, move its detailed body to the component's completed-checklist archive and leave only a short linked stub here; otherwise this active checklist becomes a second design-history document and obscures the remaining action.

- [x] **EP-1.1** -- **The shard-set query.** Which processors may host a domain: online, with
  identity carried as `(group, number)` rather than a bare number, with efficiency class and SMT
  structure available so a policy can choose one domain per core or per thread and can decide
  whether efficiency cores are peers. **Gap already identified:** parked and allocated state is not
  available at all, and pinning a domain to a parked processor is a defect a client cannot detect.
  Tracked as `SH-16.10`.
  **Done:** stated as [EP-D-1](DESIGN-NOTES.md#ep-d-1), with each of its five inputs checked against
  the model rather than assumed. Three are answered cleanly; availability is not answered at all;
  and the fourth turned up a defect the item had not anticipated.
  **`Processor::capacity` is unsafe for reading efficiency class.** It is
  `online.then(find owning Core).flatten().unwrap_or(0)`, so `0` means offline, *or* in no core
  domain, *or* genuinely class zero -- and the third is every processor on every non-hybrid machine,
  so the sentinel collides with the common legitimate value. Worse here than elsewhere, because
  Windows orders class `0` as *least* performant: on a hybrid part an unknown processor is
  indistinguishable from an efficiency core, so a policy excluding them silently drops a possible
  performance core and a policy tiering them mis-tiers it. Neither fails a functional test. Filed
  against the owning crate as `SH-16.12`; use `DomainKind::Core { efficiency_class }` meanwhile.

crates/topology-planner/CHECKLIST.md:6

• This directory contains COMPONENT.md, so it is a source component, but the change adds no component-local PLANS.md tracker. Existing source components keep that tracker (for example, crates/windows-topology-sys/PLANS.md), while the root PLANS.md is the workspace index; add the local tracker and register this checklist there so the new plan follows the repository's planning lifecycle.

# Checklist: the topology planner

Plans an arrangement of execution domains from a stated **goal** plus an **abstracted idealized**
description of a machine. See [COMPONENT.md](COMPONENT.md) for what this crate is and why it is
separate from both the topology crate and the runtime, and
[EP-D-4](DESIGN-NOTES.md#ep-d-4) for the architecture it now sits in.

crates/topology-planner/COMPONENT.md:40

• This sentence contradicts the dependency table and the planner's stated purpose: callers that want to plan must depend on topology-planner, even though the adapters and topology-model do not. As written, it makes the component's public dependency direction impossible to interpret; qualify the claim to the adapters/model rather than saying nothing depends on this crate.

`topology-model` holds the abstract machine description, **the traits the planner queries**, and
**the plan type**. Everything depends on it; **nothing depends on this crate**.

• Files reviewed: 4/4 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Originally posted by @Copilot in #98 (review)