feat(arty_io_core): add injectable I/O driver contracts

[martintmk]

Summary

Introduces arty_io_core, the shared contracts for integrating independently developed I/O drivers with an async runtime. The crate provides neither a runtime nor an I/O implementation.

• IoContext selects a DriverProvider, which creates a driver/context pair for each worker and returns initialization failures through DriverError.
• ProviderOptions, DriverOptions, DriverHandle, and on_peer_registered supply registration inputs and same-worker peer discovery.
• Cycle supplies a shared time snapshot, wait bound, blocking permission, and mutable registration through a runtime-owned PendingWorkTracker.
• Cycle::start_work registers a native interruption waker and returns a non-cloneable PendingWork. Completing or dropping the handle sends the same completion notification; interruption state, counters, and parking belong to the runtime.
• SystemTaskSpawner supplies blocking system work without exposing runtime ownership internals.
• Consuming shutdown closes admission and drains driver resources within a bounded wait, reporting graceful-cleanup failures through ShutdownError.
• The single-thread runtime example demonstrates registration and peer discovery with a no-op tracker for sample drivers that perform no I/O.

Integration

Integrated the runtime-owned work-tracking refactor unchanged, as a fast-forward from the previous PR head. The separate atomic-coordinator experiment is not included.

Requirements, design notes, API documentation, benchmarks, and tests accompany the contracts. COMPLETION_COORDINATION.md remains an exploratory runtime-implementation discussion.

CI

All 38 checks passed on the previous PR head, including coverage and mutation gates. The integrated revision passes cargo check --locked -p arty_io_core; fresh CI results are pending and are being monitored.

[martintmk]

[AI AGENT]: I reviewed all eight added public contracts (Driver, DriverContext, DriverInit, DriverProvider, Parker, Shutdown, SystemTask, and SystemTaskSpawner), their rustdoc, the example runtime, dependencies, naming, object safety, shutdown behavior, and the new public-surface tests. Two targeted probes reproduced lifecycle contradictions below. The remaining public surface is documented and intentionally narrow; I found no additional dependency, naming, performance, resilience, or test-weakening issue. CI was still running with no reported failures at the final check.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (81f1b39) to head (6065ff9).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##             main     #737     +/-   ##
=========================================
  Coverage   100.0%   100.0%             
=========================================
  Files         715      744     +29     
  Lines       96514    98556   +2042     
=========================================
+ Hits        96514    98556   +2042     

Flag	Coverage Δ
linux	99.9% <100.0%> (-0.1%)	⬇️
linux-arm	100.0% <100.0%> (ø)
scheduled	?
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.

[martintmk]

[AI AGENT]: Pragmatic Rust public API review completed with no findings. Verified the all-features cargo public-api surface, generated rustdoc JSON, package tests, clippy, spelling, the two-driver example, and the 100% coverage gate.

Coverage: reviewed Driver, DriverContext, DriverProvider, DriverInit, Parker, SystemTasks, and SystemTask from the downstream consumer and evolution perspective. The audit cannot prove runtime behavior or soundness from API output alone; those were covered separately by tests and multi-model review.

The resulting surface removes speculative Clone from DriverInit, hides Arc<dyn ...> behind the cloneable SystemTasks handle, and documents the boxed shutdown future as the deliberate object-safe shape for Box<dyn Driver<Context = C>>.

[martintmk]

Posted by an AI agent

Reviewed the exact PR head across API design, correctness, tests, performance, naming, telemetry, resilience, consistency, public API, and public documentation. I found three blocking issues and two non-blocking issues. Four are anchored inline; the remaining non-blocking issue is that the PR description still documents the obsolete DriverContext/Parker/boxed-future API and should be refreshed to match the current IoContext, interruptor, and blocking shutdown(self) contract.

Focused validation: cargo check -p arty_io_core passed; specialist runs also passed the 13 public-surface tests and the two-thread example. The focused correctness probe reproduced shutdown returning while admitted I/O was still active.

Posted by an AI agent · Non-blocking

The PR summary describes an obsolete arty_io_core API

Problem
The PR body still says DriverContext selects the provider, Driver exposes only shared-reference callbacks, Parker defines waiting, and shutdown returns an object-safe boxed future. At the pinned head, IoContext::provider selects the provider, process_completions takes &mut self, interruptor returns Waker, and shutdown(self) blocks and returns Result<(), ShutdownError>.

Why this matters
Reviewers and future readers are given a materially different registration, completion, and shutdown contract from the code and the new requirements/design documents.

Suggested fix
Refresh the PR summary to name IoContext, process_completions/interruptor, and the consuming blocking shutdown result, removing the obsolete Parker, shared-reference-callback, and boxed-future claims.

[martintmk]

Posted by an AI agent

Reviewed the current PR head across API design, correctness, tests, performance, naming, telemetry, resilience, consistency, public API, and public documentation. Three blocking issues and two non-blocking issues remain applicable.

Four are already represented by unresolved current threads: provider creation mandates panic, graceful shutdown can return before admitted I/O drains, SystemTasks::Debug remains untested, and Driver::interruptor obscures its Waker contract. One new non-blocking naming issue is posted inline: SystemTasks names submitted work rather than its spawning capability.

Focused validation passed all 13 arty_io_core public-surface tests and the two-thread runtime example. Paired cargo public-api and rustdoc JSON extraction completed for the exact base/head snapshot.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved handle-validation and coverage issues must be addressed before approval.

Review effort: Lite
Findings: 1 · 2

Open (3)

• Expose the interruption waker to driver implementations
• Coverage gate fails for unexecuted formatter and default paths
• Retained wakers can interrupt after driver shutdown

Resolved since last review (1)

• Expose the interruption waker through Cycle

[martintmk]

begin cycle should receive max wait, start time and return cycle, constructor should be internal

[martintmk]

Suggested change

	pub fn start_work(&self) -> PendingWork {
	pub fn start_work(&mut self) -> PendingWork {

[Copilot]

Copilot review overview

🟡 Changes recommended

Add the missing public-surface coverage assertions and correct the documented Linux path separators.

Review effort: Lite
Findings: 1 · 2 · 1

Open (4)

• Expose the interruption waker to driver implementations
• Coverage gate fails for unexecuted formatter and default paths
• Retained wakers can interrupt after driver shutdown
• Use Linux path separators in the reproduction report paths · New

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved coordinator lifecycle and accounting issues, documentation path errors, and dependency configuration require correction.

Review effort: Lite
Findings: 2 · 2 · 1

Open (5)

• Invalidate retained wakers when their driver is dropped · New
• Expose the interruption waker to driver implementations
• Coverage gate fails for unexecuted formatter and default paths
• Retained wakers can interrupt after driver shutdown
• Use Linux path separators in the reproduction report paths

[Copilot]

Copilot review overview

🔵 Needs a closer look

The broad runtime contract changes and unresolved documentation feedback warrant human review.

Review effort: Lite
Findings: 2 · 2 · 1

Open (5)

• Invalidate retained wakers when their driver is dropped
• Expose the interruption waker to driver implementations
• Coverage gate fails for unexecuted formatter and default paths
• Retained wakers can interrupt after driver shutdown
• Use Linux path separators in the reproduction report paths

Previously missed (1)

In code that hasn't changed since last review

Use Linux path separators in coordinator-tools installation instructions

docs/​arty-io-core-coordinator-performance.md:213

The reproduction instructions say they are for Linux, but this sentence renders the install location with Windows separators (target\\coordinator-tools). In the stated shell, that does not describe the directory created by the preceding command; use target/coordinator-tools so the documented GUNGRAUN_RUNNER path is actionable.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved moderate review findings remain in coverage configuration, published-package testing, and performance documentation.

Review effort: Lite
Findings: 2

Open (2)

• Add or remove unreproducible benchmark report · New
• Use Linux path separators in the reproduction report paths

Resolved since last review (4)

• Invalidate retained wakers when their driver is dropped
• Expose the interruption waker to driver implementations
• Coverage gate fails for unexecuted formatter and default paths
• Retained wakers can interrupt after driver shutdown

[Copilot]

Copilot review overview

🔵 Needs a closer look

Two moderate issues remain unresolved, along with one documentation path nit.

Review effort: Lite
Findings: 2

Open (2)

• Add or remove unreproducible benchmark report
• Use Linux path separators in the reproduction report paths

Previously missed (1)

In code that hasn't changed since last review

Use POSIX paths in Linux reproduction instructions

docs/​arty-io-core-coordinator-performance.md:213

This section is explicitly written for a Linux checkout, but the inline path uses Windows backslashes. On Linux target\coordinator-tools is a different literal path from the target/coordinator-tools path used by the command above, and the later artifact paths repeat the same separator issue. Use POSIX separators consistently in the Linux reproduction instructions.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Address the benchmark-report mismatch and the coverage, packaging, and documentation findings before approval.

Review effort: Lite
Findings: 2

Open (2)

• Add or remove unreproducible benchmark report
• Use Linux path separators in the reproduction report paths

[github-actions]

⚠️ SemVer check advisory

Inconclusive comparisons

cargo semver-checks could not complete the following comparisons. These failures are informational because an unbuildable baseline is not evidence of a breaking API change.

metabench (exit 101)

     Cloning 81f1b39b133ece73a377e8673f882444ffcd3cab
    Building metabench v0.1.1 (current)
error: running cargo-doc on crate 'metabench' failed with output:
-----
   Compiling proc-macro2 v1.0.107
   Compiling quote v1.0.47
   Compiling unicode-ident v1.0.26
   Compiling serde_core v1.0.229
   Compiling zmij v1.0.23
   Compiling serde v1.0.229
   Compiling serde_json v1.0.151
   Compiling libc v0.2.189
    Checking cfg-if v1.0.5
    Checking itoa v1.0.18
   Compiling syn v3.0.6
   Compiling syn v2.0.119
    Checking memchr v2.8.3
   Compiling zerocopy v0.8.59
    Checking bitflags v2.13.2
   Compiling find-msvc-tools v0.1.14
   Compiling semver v1.0.28
   Compiling shlex v2.0.1
   Compiling hashbrown v0.17.1
   Compiling rustversion v1.0.23
   Compiling winnow v1.0.4
   Compiling equivalent v1.0.2
   Compiling indexmap v2.14.2
   Compiling cc v1.5.1
   Compiling toml_parser v1.1.3+spec-1.1.0
   Compiling serde_derive v1.0.229
   Compiling rustc_version v0.4.1
   Compiling zerocopy-derive v0.8.59
   Compiling derive_more-impl v2.1.1
   Compiling toml_datetime v1.1.1+spec-1.1.0
   Compiling rustix v1.1.5
   Compiling autocfg v1.5.1
   Compiling toml_edit v0.25.15+spec-1.1.0
   Compiling num-traits v0.2.19
   Compiling alloca v0.4.0
   Compiling gungraun-macros v0.9.1
    Checking either-or-both v0.3.1
   Compiling proc-macro-error-attr3 v3.1.1
    Checking regex-syntax v0.8.11
   Compiling thiserror v2.0.21
    Checking anstyle v1.0.14
   Compiling bincode-next v3.1.1
   Compiling cfg_aliases v0.2.2
    Checking either v1.18.0
    Checking ciborium-io v0.2.2
   Compiling getrandom v0.4.3
    Checking linux-raw-sys v0.12.1
    Checking clap_lex v1.1.1
    Checking clap_builder v4.6.7
    Checking itertools v0.13.0
   Compiling nix v0.31.3
    Checking half v2.7.1
    Checking regex-automata v0.4.18
    Checking ciborium-ll v0.2.2
   Compiling proc-macro-error3 v3.1.1
    Checking rapidhash v4.5.1
   Compiling proc-macro-crate v3.5.0
   Compiling derive_more v2.1.1
   Compiling thiserror-impl v2.0.21
   Compiling gungraun v0.19.4
    Checking cast v0.3.0
    Checking unty-next v0.1.2
   Compiling pastey v0.2.3
    Checking same-file v1.0.6
    Checking walkdir v2.5.0
    Checking criterion-plot v0.8.2
    Checking regex v1.13.1
   Compiling metabench_macros_impl v0.1.1 (/home/runner/work/oxidizer/oxidizer/crates/metabench_macros_impl)
    Checking gungraun-runner v0.20.0
    Checking ciborium v0.2.2
    Checking clap v4.6.7
    Checking gungraun-runner v0.19.4
    Checking folo_utils v0.1.14
    Checking tinytemplate v1.2.1
    Checking nix v0.27.1
    Checking page_size v0.6.0
    Checking oorandom v11.1.5
    Checking fastrand v2.5.0
    Checking once_cell v1.21.4
   Compiling metabench v0.1.1 (/home/runner/work/oxidizer/oxidizer/crates/metabench)
    Checking jiff-core v0.1.1
    Checking anes v0.1.6
    Checking criterion v0.8.2
    Checking gungraun-summary v6.0.0
error[E0432]: unresolved import `gungraun_runner::api::ValgrindTool`
  --> /home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/gungraun-summary-6.0.0/src/v6.rs:10:59
   |
10 |     CachegrindMetric, DhatMetric, ErrorMetric, EventKind, ValgrindTool,
   |                                                           ^^^^^^^^^^^^ no `ValgrindTool` in `api`

error[E0432]: unresolved imports `gungraun_runner::metrics::model::MetricsDiff`, `gungraun_runner::metrics::model::MetricsSummary`
  --> /home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/gungraun-summary-6.0.0/src/v6.rs:12:63
   |
12 | pub use gungraun_runner::metrics::model::{Metric, MetricKind, MetricsDiff, MetricsSummary};
   |                                                               ^^^^^^^^^^^  ^^^^^^^^^^^^^^ no `MetricsSummary` in `metrics::model`
   |                                                               |
   |                                                               no `MetricsDiff` in `metrics::model`

error[E0432]: unresolved imports `gungraun_runner::summary::model::Diffs`, `gungraun_runner::summary::model::FlamegraphSummary`, `gungraun_runner::summary::model::ProfileInfo`, `gungraun_runner::summary::model::SummaryFormat`, `gungraun_runner::summary::model::SummaryOutput`, `gungraun_runner::summary::model::ToolMetricSummary`
  --> /home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/gungraun-summary-6.0.0/src/v6.rs:14:38
   |
14 |     BenchmarkKind, BenchmarkSummary, Diffs, FlamegraphSummary, Profile, ProfileData, ProfileInfo,
   |                                      ^^^^^  ^^^^^^^^^^^^^^^^^                        ^^^^^^^^^^^ no `ProfileInfo` in `summary::model`
   |                                      |      |
   |                                      |      no `FlamegraphSummary` in `summary::model`
   |                                      no `Diffs` in `summary::model`
15 |     ProfilePart, ProfileTotal, Profiles, SCHEMA_VERSION, SummaryFormat, SummaryOutput,
   |                                                          ^^^^^^^^^^^^^  ^^^^^^^^^^^^^ no `SummaryOutput` in `summary::model`
   |                                                          |
   |                                                          no `SummaryFormat` in `summary::model`
16 |     ToolMetricSummary, ToolRegression,
   |     ^^^^^^^^^^^^^^^^^ no `ToolMetricSummary` in `summary::model`

    Checking command-group v5.0.1
For more information about this error, try `rustc --explain E0432`.
error: could not compile `gungraun-summary` (lib) due to 3 previous errors
warning: build failed, waiting for other jobs to finish...

-----

error: failed to build rustdoc for crate metabench v0.1.1
note: this is usually due to a compilation error in the crate,
      and is unlikely to be a bug in cargo-semver-checks
note: the following command can be used to reproduce the error:
      cargo new --lib example &&
          cd example &&
          echo '[workspace]' >> Cargo.toml &&
          cargo add --path /home/runner/work/oxidizer/oxidizer/crates/metabench &&
          cargo check &&
          cargo doc

error: aborting due to failure to build rustdoc for crate metabench v0.1.1