feat(thread_aware_core): add the stable core crate for thread-aware state

[martintmk]

Summary

Adds thread_aware_core, the stable vocabulary that thread-aware libraries share. Nothing
else in the workspace changes.

• ThreadAware notifies a value that it has moved, via
  relocate(source: Option<&Thread>, destination: &Thread). The call is advisory: a value
  must remain correct if it is never called, called twice, or called with a Thread it has
  never seen. That single property is what lets the method be infallible and lets a runtime
  call it opportunistically.
• Thread records where a value runs — Owner (which runtime owns it), a
  std::thread::ThreadId, and NumaNode (the memory closest to that thread). Fields are
  private and read through accessors.
• Owner identity is assigned, not supplied: every new owner is unique, so two runtimes
  alive at once cannot collide. It also reports min_threads, the smallest number of threads
  its runtime runs, so a value can pre-size per-thread state before it has seen any of them.
• NumaNode is an opaque u32 newtype built with an inherent const fn new(u32).
• Nothing reaches a consumer's dependency graph; the only manifest entry is a test-only
  dev-dependency. The std feature is on by default and adds implementations for HashMap,
  Path and PathBuf. With default-features = false the crate needs only alloc and
  pointer-width atomics; Thread then loses its thread id and cannot be constructed, leaving
  Owner and NumaNode readable so a no_std library can still implement the trait.
• docs/DESIGN.md records why the crate is split out, and the rules that let Thread gain
  coordinates later without breaking callers or changing behaviour.
  docs/STABILIZATION.md records the stable boundary.

Why Owner assigns its own identity

Callers used to choose the number, and the documentation warned at length that a collision
was "worse than a slowdown" and that keeping owners distinct was the embedding application's
problem. Taking the identity from a process-wide counter removes the hazard outright rather
than documenting it. Equality and hashing use identity alone.

min_threads is a floor, not an estimate. 0 means the runtime promises none and spawns on
demand, which falls through HashMap::with_capacity as a no-op, so both cases share one
expression at the call site. It was named threads_hint first; in std, _hint already means
a bound — size_hint returns a lower bound plus an optional upper, and overshooting is a bug
— so "hint" would have contradicted the suffix while leaving 0 a magic value.

Why the ids take new rather than From<u16>

A From<integer> impl on a permanently stable type is a one-shot commitment. Every way of
evolving one is breaking, verified against rustc:

Later change	Result
Replace From<u16> with From<u32>	breaks every caller passing a typed u16 (E0277)
Add From<u32> beside From<u16>	breaks unsuffixed literals: from(1) falls back to i32 (E0277)
Add From<i32>	no error at all — silently re-resolves from(1) to the new impl

cargo semver-checks 0.48 reports "no semver update required" for all three, so none of them
would be caught in review. NumaNode is therefore u32-backed with an inherent new. The
accepted width already exceeds any node count real hardware reaches — Windows' own topology
APIs report NUMA nodes as USHORT — and a wider or fallible constructor can still be added
later under a different name without touching existing callers.

Provided implementations

Containers forward to what they hold; primitives and other types with nothing tied to a
thread get an empty implementation. Three cases are deliberately absent:

• References (&str, &Path) — relocating through one would adapt something the value
  only borrows, and whoever owns it is relocated on its own account.
• Cow — relocating a borrowed one has to clone it into owned storage first, which is
  too much work to hide behind an advisory call. It can return later if a caller wants it.
• Arc and sets — whether a shared allocation should split per thread depends on what it
  holds, and mutating a set element could change its hash and corrupt the container.

Naming

thread_aware_core::Thread shares a name with std::thread::Thread but is a different kind
of thing: an immutable coordinate that owns no OS resource. Importing both unqualified is
E0252, and both expose an identical id(&self) -> ThreadId. This is called out in the crate
docs and in a # Relation to std::thread::Thread section on the type. Raised deliberately
here in case reviewers would prefer a different name.

Scope

thread_aware is unchanged and still ships its own Affinity-based API. Nothing depends
on thread_aware_core yet; adoption is left for a later change. The diff against main is
the new crate plus its workspace wiring (Cargo.toml, Cargo.lock, CHANGELOG.md,
README.md) and nothing more.

Validation

• 25 unit tests and 14 doctests with --all-features; 25 unit tests and 12 doctests with
  --no-default-features. One doctest is ignored: it demonstrates
  #[derive(ThreadAware)], which lives in thread_aware, and compiling it here would
  require the dependency the example exists to argue against.
• Clippy in both feature configurations, rustdoc with -D warnings --cfg docsrs, formatting,
  spelling, and the generated README all pass.
• Static assertions pin the auto traits (Send, Sync, Unpin, UnwindSafe,
  RefUnwindSafe) on all three public types, and assert_obj_safe! pins dyn-compatibility of
  ThreadAware. Both guard silent regressions: a coordinate added later that is not Sync
  would strip that property with no signature change, and a defaulted-but-generic trait method
  would keep every impl compiling while breaking every Box<dyn ThreadAware>.
• Documentation and API shape went through repeated independent model-backed reviews. Those
  found real defects rather than wording nits: a counter width that would wrap and reissue a
  live identity, a claim that ThreadId is the operating-system thread id (it explicitly is
  not), an equality claim that was false under no_std, and an Eq/Hash test that passed
  vacuously because it compared a value with its own copy.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (edae40d) to head (197bd04).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #643   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         560      562    +2     
  Lines       60859    60945   +86     
=======================================
+ Hits        60859    60945   +86     

Flag	Coverage Δ
linux	100.0% <100.0%> (?)
linux-arm	100.0% <100.0%> (?)
windows	100.0% <100.0%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

✅ Version increments look sufficient

cargo semver-checks compared the 1 crate(s) this PR publishes against their previous version-bump commit in git history. Every version increment is sufficient for the detected API changes.

Crate	Baseline	Baseline commit	This PR	Minimum required	Status
thread_aware_core	new crate	—	0.1.0	0.1.0	✅ ok

This check is informational and does not block the merge.

View the check run

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

crates/thread_aware_core/src/lib.rs:18

• The PR description talks about Place/Origin and u16 newtypes, but the actual API added here is Thread + Owner/NumaNode with u32 storage. Please align the PR description (or, if the intent really is Place/Origin, align the code/docs) so reviewers and future readers don’t have two conflicting vocabularies for the same change.

//! This crate contains the small API shared by thread-aware libraries:
//!
//! - [`ThreadAware`] notifies a value that it has moved.
//! - [`Thread`] records where it now runs: which runtime, which OS thread, and which memory is
//!   closest to it.

crates/thread_aware_core/src/thread_aware.rs:164

• Unit-test modules in this repo are typically annotated with #[cfg_attr(coverage_nightly, coverage(off))] so the test-only lines don’t count against the coverage gate. This file adds a #[cfg(test)] mod tests without that attribute, which is inconsistent with the established pattern (e.g., crates/tick/src/error.rs:103-105).

#[cfg(test)]
mod tests {

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Previously missed (1) — in code that hasn't changed since the last review.

crates/thread_aware_core/src/lib.rs:62

• In this doc example, “build dependency” is easy to misread as Cargo [build-dependencies]. Since thread_aware would be a normal/proc-macro dependency used at compile time, consider wording that more precisely communicates “implementation-only dependency” / “not part of the public API”.

//! // A build dependency, not part of what this library promises.

crates/thread_aware_core/src/thread_aware.rs:164

• The test module here is missing the #[cfg_attr(coverage_nightly, coverage(off))] attribute that other modules in this crate use (e.g. src/thread.rs and src/impls.rs). Without it, these tests can count against the coverage gate in coverage runs.

#[cfg(test)]
mod tests {

crates/thread_aware_core/src/thread.rs:33

• The PR description says the runtime/node ids are u16 newtypes (and refers to Origin/Place), but the stable API implemented here uses Owner(u32) (and Thread). Please align the PR description (or the code/docs) so reviewers/users aren’t left with conflicting API details.

#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct Owner(u32);

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

crates/thread_aware_core/src/thread_aware.rs:165

• mod tests here is missing #[cfg_attr(coverage_nightly, coverage(off))]. Other test modules in this crate already apply it (e.g. src/thread.rs and src/impls.rs) to avoid test-only lines counting against the 100% coverage gate; this module should do the same for consistency.

#[cfg(test)]
mod tests {

[martintmk]

[AI AGENT]: I reviewed this as a crate publication, so I treated the entire reachable surface as new: ThreadAware (supertrait, required method, dyn-compatibility, downstream implementability), Thread / Owner / NumaNode (visibility, constructors, derives, accessors, auto traits), the std feature boundary and what it removes, the ~90 ThreadAware impls in impls.rs read as a coherence lattice, the manifest and packaged contents, and DESIGN.md / STABILIZATION.md as the stabilization argument.

I relied on this PR's own CI for lint, format and the full suite (green at 604e252, with fuzz-testing still pending and mutation-testing skipped) rather than re-running it, and used narrow local probes only to prove specific claims: an E0119 probe for the reference impls, two failing Cow tests, an E0277 probe for BTreeMap<NumaNode, _> under --no-default-features, cargo package --list for the packaged set, and cargo build / cargo test -p thread_aware_core --lib in both feature configurations to check each proposed fix.

Two findings I would act on before this ships. The concrete &str and &Path impls permanently foreclose the general impl<T: Sync + ?Sized> ThreadAware for &T — verified as a hard E0119 conflict — and that is the one thing in this PR the additive escape hatches in DESIGN.md cannot recover. And Cow::relocate clones borrowed data into a fresh allocation on the first relocation, including when source == destination, which contradicts three of the trait's own documented requirements and is precisely the allocation a Cow<'static, str> field exists to avoid.

Three non-blocking notes, inline: Owner and NumaNode are not Ord, so a no_std consumer cannot key the BTreeMap the crate docs tell them to use; DESIGN.md's "every coordinate has a default variant" rule is not applied to the two coordinates shipping now, leaving no way to express "unknown node"; and my answer to the naming question you raised is on thread.rs.

The rest of the public-contract pass came out clean, and that is worth stating rather than omitting. The Send supertrait plus the assert_obj_safe! / assert_impl_all! pins are the right guards for the two silent-regression classes you identified; private fields with accessors do make Thread extensible without #[non_exhaustive]; the inherent new over From<integer> analysis holds and I could not find a fourth evolution path it misses; and nothing reaches a consumer's graph — the only manifest entry is a dev-dependency, and cargo package --list confirms the LFS-tracked logo.png and favicon.ico stay out of the packaged set (12 files, all src/, docs/**/*.md, examples/, README.md, Cargo.toml), referenced by absolute URL as the packaging guidelines require. I skipped the 0.1.0-versus-1.0 wording in STABILIZATION.md and the missing coverage(off) on thread_aware.rs's test module, since copilot-pull-request-reviewer already has open threads on both.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

crates/thread_aware_core/src/thread_aware.rs:165

• This crate follows the pattern of excluding #[cfg(test)] mod tests from the coverage gate via #[cfg_attr(coverage_nightly, coverage(off))] (as in thread.rs and impls.rs), but this tests module is missing that attribute. Add it here for consistency and to avoid test-only lines counting toward coverage.

#[cfg(test)]
mod tests {

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

crates/thread_aware_core/src/thread.rs:89

• Owner::new uses AtomicUsize::fetch_add, which wraps on overflow. That would violate the documented guarantee that every new Owner is unique by potentially reissuing an identity once the counter wraps (especially on 32-bit targets). Consider using fetch_update with checked_add to fail fast on exhaustion without mutating the counter into a wrapped state.

    pub fn new(min_threads: usize) -> Self {
        Self {
            id: NEXT_OWNER.fetch_add(1, Ordering::Relaxed),
            min_threads,
        }

crates/thread_aware_core/src/thread_aware.rs:165

• This crate consistently marks #[cfg(test)] mod tests with #[cfg_attr(coverage_nightly, coverage(off))] to keep test-only lines from counting against the 100% coverage gate (e.g. crates/tick/src/error.rs). This test module is missing that attribute.

#[cfg(test)]
mod tests {

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (1)

crates/thread_aware_core/src/thread_aware.rs:165

• Tests modules in this repo are consistently annotated with #[cfg_attr(coverage_nightly, coverage(off))] so unit-test-only lines don’t count against the coverage gate. This mod tests is missing that attribute (unlike thread.rs / impls.rs in the same crate).

#[cfg(test)]
mod tests {

[Copilot]

Pull request overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (1)

crates/thread_aware_core/src/thread_aware.rs:165

• The unit-test module here is missing #[cfg_attr(coverage_nightly, coverage(off))]. Other test modules in this new crate already apply it (e.g., thread.rs and impls.rs), and omitting it can cause test-only lines to count against the coverage gate.

#[cfg(test)]
mod tests {