docs(runtime): explain shutdown requirements for service loops

[Coldwings]

Description

Documents that graceful scheduler shutdown drains accepted work but does not
request application-level accept loops, periodic timers, or other service tasks
to stop.

Callers must cancel or wake those loops and await them before an unbounded
shutdown, or use a finite timeout and accept force-stop semantics.

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 #1010

Changes Made

Core Changes

• Extend the scheduler::shutdown() header contract with service-loop guidance.
• Add the caller obligation to the central API contract table.
• Explain the finite-timeout and force-stop boundary in the API reference.
• Record the clarified lifecycle contract in the Unreleased changelog.

API Changes (if applicable)

No signature or runtime behavior changes. This PR documents the existing
contract.

Testing

Unit Tests

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

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
# passed

This documentation-only change was not compiled or tested locally. GitHub
Actions provides executable validation.

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
• 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
• I have considered the impact on existing users
• I have updated CHANGELOG.md

Performance (if applicable)

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

Reviewer Guidance

Areas requiring special attention:

• Whether shutdown's drain behavior is clearly separated from application cancellation.
• Whether finite-timeout force-stop consequences are described accurately.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Coldwings]

Independent read-only review summary:

• Scope: the current PR head against its main base.
• Lens: graceful-drain behavior, application cancellation responsibility, timeout force-stop wording, and cross-document consistency.
• Blocking findings: none.
• Non-blocking findings: none.
• Residual validation gap: the review was static; GitHub Actions remains the executable validation gate.

Verdict: no blocking objections remain for the reviewed head.

[Coldwings]

Independent read-only re-review summary for the rebased head:

• Scope: the current PR head against the updated main base after PRs feat(io): reduce io_uring initialization log noise #1012 and docs(net): define listener close and accept shutdown contract #1013 merged.
• Lens: shutdown drain/force-stop semantics, contract consistency, and conflict-resolution preservation.
• Blocking findings: none.
• Non-blocking findings: none.
• Conflict-resolution check: the feat(io): reduce io_uring initialization log noise #1012 and docs(net): define listener close and accept shutdown contract #1013 changelog/documentation content remains present, and this PR's diff is still limited to its original four files.
• Residual validation gap: the review was static; the newly triggered GitHub Actions run remains the executable validation gate.

Verdict: no blocking objections remain for the rebased head.