docs(runtime): define retiring worker drain contract

[Coldwings]

Description

Document the scheduler's existing retire-and-drain resize contract. A shrink
publishes the smaller logical scheduling range without waiting for removed
workers to finish draining their worker-local I/O; the previous public wording
could be read as a synchronous physical-thread stop.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Performance improvement (optimization that improves speed/memory usage)
• Documentation (changes to documentation, comments, or examples)
• Refactoring (code changes that neither fix bugs nor add features)
• Tests (adding or modifying tests)
• Build/CI (changes to build system, CI configuration, or dependencies)

Related Issues

Closes #1079

Changes Made

Core Changes

• Define num_threads() as the logical scheduling range during retirement.
• State that active_tasks() and pending_tasks() continue to account for draining workers.
• Document that a later grow can wait for slot reuse and that long-lived I/O needs application cancellation or deadlines.
• Identify finite-budget/forced shutdown as a non-graceful escape rather than adding a retirement timeout.
• Correct stale header comments that attributed worker joins to the shrink path itself.

API Changes (if applicable)

None. This documents the existing implementation and responsibility boundary.

Migration Guide (if breaking change)

Not applicable.

Testing

Unit Tests

• Added new tests for the changes
• Updated existing tests if needed
• All tests pass locally

Documentation and comments only; no runtime behavior changed, so the code test
suite was not rebuilt.

Integration Tests

• Tested with existing examples
• Tested in real-world scenarios (if applicable)

Sanitizer Testing

• Tested with ASAN (AddressSanitizer)
• Tested with TSAN (ThreadSanitizer)
• No new warnings or errors

Test Results

git diff --check origin/main...HEAD

Checklist

Code Quality

• My code follows the project's code style
• I have added/updated comments for complex logic
• I have removed any debug code, TODOs, or commented-out code
• My changes generate no new warnings

Documentation

• I have updated documentation (wiki, README, code comments)
• I have added examples for new features (if applicable)
• I have updated API documentation (if applicable)

Testing

• I have added tests that prove my fix is effective or my feature works
• New and existing unit tests pass locally with my changes
• I have tested with ASAN and TSAN

Compatibility

• My changes are backward compatible (or I've documented breaking changes)
• I have considered the impact on existing users
• I have updated CHANGELOG.md (if applicable)

Performance (if applicable)

• I have considered the performance impact
• I have added benchmarks for performance-critical changes

Screenshots / Diagrams

Not applicable.

Additional Notes

This PR intentionally does not add a retirement deadline. A fixed deadline
would allow a worker to stop polling operations that are still owned by its I/O
context and could orphan otherwise valid long-running I/O.

Reviewer Guidance

Areas requiring special attention:

• Consistency between scheduler accounting and the documented logical/physical worker distinction.
• Wording around non-graceful shutdown and application-owned cancellation.

Questions for reviewers:

• Does each public documentation surface describe the same resize lifecycle?

[Copilot]

Pull request overview

Documents the scheduler’s asynchronous retire-and-drain behavior during pool shrink.

Changes:

• Defines logical versus physical worker accounting during retirement.
• Documents unbounded drain risks, slot-reuse waits, and shutdown escape paths.
• Corrects scheduler API comments and release notes.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
wiki/Performance-Tuning.md	Explains resize responsiveness and metrics.
wiki/Core-Concepts.md	Defines the retirement lifecycle.
wiki/API-Reference.md	Clarifies public scheduler API semantics.
wiki/API-Contracts.md	Adds the resize responsibility contract.
include/elio/runtime/scheduler.hpp	Corrects public and internal comments.
CHANGELOG.md	Records the clarified contract.

---

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

[Coldwings]

@copilot Please review the updated current head only.

[Copilot]

@copilot Please review the updated current head only.

Reviewed the current head (c58a466). The six changed files are mutually consistent and accurately reflect the implementation:

• scheduler.hpp — num_threads(), pending_tasks(), active_tasks(), and the set_thread_count() guard comment all use "logical scheduling range" / "slot reuse waits for and joins a draining worker" wording, which matches the deferred-join behavior correctly.
• Wiki pages — API-Contracts.md, API-Reference.md, Core-Concepts.md, and Performance-Tuning.md are consistent on: shrink publishes first and returns, physical thread exits later; accounting includes draining workers; later grow waits at slot reuse; shutdown_force() is the non-graceful escape with orphan-I/O trade-off stated; no independent retirement timeout.
• CHANGELOG.md — Entry accurately summarises the documented contract and is placed correctly.

One cosmetic note: in Performance-Tuning.md the new monitoring paragraph (During retirement, pending_tasks()…) runs directly into Workers publish… without a blank line. Not a correctness issue.

No inconsistencies or incorrect statements found.

[Coldwings]

@copilot Please review the updated current head only after the paragraph-separation fix.

[Copilot]

@copilot Please review the updated current head only after the paragraph-separation fix.

Current head (b7e5f64) looks good. The blank lines added before and after the During retirement… paragraph in Performance-Tuning.md give it proper separation. Content is unchanged and consistent with the rest of the PR. No issues found.

[Coldwings]

@copilot please re-review only; do not make direct code modifications.

[Copilot]

@copilot please re-review only; do not make direct code modifications.

Re-reviewed both commits at current head (291e530). All six files remain mutually consistent and accurately describe the implementation:

• scheduler.hpp — num_threads(), pending_tasks(), active_tasks(), and the set_thread_count() guard comment are all correct for the deferred-join model.
• Wiki pages — API-Contracts.md, API-Reference.md, Core-Concepts.md, and Performance-Tuning.md agree on: shrink publishes first and returns; physical threads drain asynchronously; accounting includes draining workers; slot reuse may wait; shutdown_force() is the non-graceful escape with the orphan-I/O trade-off documented.
• CHANGELOG.md — Entry is accurate and correctly placed.
• Paragraph separation (291e530) — blank lines before and after the During retirement… block are in place; no content changes.

No inconsistencies or inaccurate statements found.