aiogram-coordination 0.1.0__tar.gz

aiogram_coordination-0.1.0/.gitattributes

@@ -0,0 +1,9 @@
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary

aiogram_coordination-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,20 @@
+name: Bug report
+description: Report a reproducible navigation or recovery problem.
+body:
+  - type: markdown
+    attributes:
+      value: For sensitive vulnerabilities, follow SECURITY.md. Remove tokens, credentials and private message text.
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python, aiogram-coordination, aiogram and optional redis-py versions; memory or Redis backend; FSM isolation configuration.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Include expected versus actual behavior and sanitized traceback. For recovery issues, state which effect stages are confirmed or unknown.
+    validations:
+      required: true

aiogram_coordination-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,15 @@
+name: Feature request
+description: Describe a navigation use case or API improvement.
+body:
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use case
+      description: What behavior does your application need? Include alternatives already considered.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: Describe API, backend, recovery and compatibility implications where relevant.

aiogram_coordination-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Change
+
+Describe the problem and resulting behavior.
+
+## Verification
+
+List checks actually run and remaining limitations. Mention real-Redis coverage for
+storage, concurrency or recovery changes.
+
+## Compatibility
+
+Describe any public API, persisted-schema, callback ownership or FSM impact.
+Include a `CHANGES/` fragment for user-visible changes. Keep aiogram-idle and Redis
+optional, and do not include credentials or generated security reports.

aiogram_coordination-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,154 @@
+name: CI
+on: [push, pull_request]
+permissions:
+  contents: read
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen --extra redis --python 3.12
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: uv run --no-sync pyright src examples
+      - run: uv run --no-sync python tools/check_version.py
+      - run: uv run --no-sync towncrier build --draft
+      - run: uv run --no-sync pytest
+      - run: uv run --no-sync mkdocs build --strict
+      - run: uv build
+      - run: uv run --no-sync twine check dist/*
+      - name: Independently install wheel and sdist without optional dependencies
+        shell: bash
+        run: |
+          for artifact in dist/*.whl dist/*.tar.gz; do
+            target=$(mktemp -d)
+            uv venv --python 3.12 "$target/env"
+            uv pip install --python "$target/env/bin/python" "$artifact" pytest pytest-asyncio hypothesis
+            cp -R tests examples tools "$target/"
+            cp pyproject.toml "$target/"
+            cd "$target"
+            "$target/env/bin/python" tools/check_install.py
+            "$target/env/bin/python" tools/check_version.py
+            "$target/env/bin/python" -m pytest -q
+            cd "$GITHUB_WORKSPACE"
+          done
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+  compatibility:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13', '3.14']
+        aiogram: [minimum, latest]
+        exclude:
+          # aiogram 3.22 pins dependencies released before Python 3.14 support.
+          - python: '3.14'
+            aiogram: minimum
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen --python '${{ matrix.python }}'
+      - shell: bash
+        run: |
+          if [ '${{ matrix.aiogram }}' = minimum ]; then
+            uv pip install 'aiogram==3.22.0'
+          else
+            uv pip install --upgrade 'aiogram>=3.22,<4'
+          fi
+      - run: uv run --no-sync pytest
+      - run: uv run --no-sync python examples/memory_scope.py
+  redis:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.12', '3.14']
+        redis-client: [minimum, latest]
+        server: ['7']
+        include:
+          - python: '3.12'
+            redis-client: latest
+            server: '8'
+    services:
+      redis:
+        image: redis:${{ matrix.server }}-alpine
+        ports: ['6379:6379']
+        options: --health-cmd "redis-cli ping" --health-interval 5s --health-timeout 3s --health-retries 10
+    env:
+      AIOGRAM_COORDINATION_REDIS_URL: redis://localhost:6379/0
+      AIOGRAM_COORDINATION_REQUIRE_REDIS: '1'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen --extra redis --python '${{ matrix.python }}'
+      - if: matrix.redis-client == 'minimum'
+        run: uv pip install 'redis==5.0.8'
+      - run: uv run --no-sync pytest --cov=aiogram_coordination --cov-report=term-missing --cov-report=xml --cov-fail-under=80
+      - name: Verify Redis-enabled installed artifacts against the real server
+        if: matrix.python == '3.12' && matrix.redis-client == 'latest' && matrix.server == '7'
+        shell: bash
+        run: |
+          uv build
+          for artifact in dist/*.whl dist/*.tar.gz; do
+            target=$(mktemp -d)
+            uv venv --python 3.12 "$target/env"
+            uv pip install --python "$target/env/bin/python" "${artifact}[redis]" pytest pytest-asyncio hypothesis
+            cp -R tests examples tools "$target/"
+            cp pyproject.toml "$target/"
+            cd "$target"
+            "$target/env/bin/python" tools/check_install.py --redis
+            "$target/env/bin/python" -m pytest -q
+            cd "$GITHUB_WORKSPACE"
+          done
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: redis-coverage-${{ matrix.python }}-${{ matrix.redis-client }}-${{ matrix.server }}
+          path: coverage.xml
+          if-no-files-found: warn
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen --extra redis --python 3.12
+      # Keep the full low-severity inventory; the following invocation owns the gate.
+      - run: uv run --no-sync bandit -r src -f json -o bandit-report.json --exit-zero
+      - run: uv run --no-sync bandit -r src -ll
+      - name: Audit the resolved environment
+        if: always()
+        run: uv run --no-sync pip-audit --format=json --output=pip-audit-report.json
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-reports
+          path: |
+            bandit-report.json
+            pip-audit-report.json
+          if-no-files-found: warn
+  checks:
+    name: Required checks
+    if: always()
+    needs: [quality, compatibility, redis, security]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require successful jobs
+        env:
+          RESULTS: ${{ toJSON(needs) }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          results = json.loads(os.environ["RESULTS"])
+          failed = [name for name, job in results.items() if job["result"] != "success"]
+          if failed:
+              raise SystemExit("Required jobs did not pass: " + ", ".join(failed))
+          PY

aiogram_coordination-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,91 @@
+name: Publish verified release
+
+on:
+  workflow_dispatch:
+    inputs:
+      manifest_sha256:
+        description: SHA256 of the independently verified GitHub release SHA256SUMS
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+      - name: Download the exact reviewed release artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release download "$GITHUB_REF_NAME" --pattern '*.whl' --pattern '*.tar.gz' --pattern SHA256SUMS --dir dist
+      - name: Validate tag, distribution names and independently supplied checksums
+        env:
+          MANIFEST_SHA256: ${{ inputs.manifest_sha256 }}
+        run: |
+          python - <<'PYVERIFY'
+          import hashlib
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+          project = tomllib.loads(Path('pyproject.toml').read_text())['project']
+          version = project['version']
+          if os.environ['GITHUB_REF_NAME'] != 'v' + version:
+              raise SystemExit('Tag does not match project version')
+          expected_digest = os.environ['MANIFEST_SHA256']
+          if not re.fullmatch(r'[a-f0-9]{64}', expected_digest):
+              raise SystemExit('Expected an independently verified SHA256 digest')
+          manifest = Path('dist/SHA256SUMS')
+          if hashlib.sha256(manifest.read_bytes()).hexdigest() != expected_digest:
+              raise SystemExit('Release checksum manifest differs from reviewed input')
+          name = project['name'].replace('-', '_')
+          expected = {f'{name}-{version}-py3-none-any.whl', f'{name}-{version}.tar.gz'}
+          if {p.name for p in Path('dist').iterdir()} != expected | {'SHA256SUMS'}:
+              raise SystemExit('Unexpected release files')
+          checked = set()
+          for line in manifest.read_text().splitlines():
+              digest, filename = line.split()
+              if filename not in expected or filename in checked:
+                  raise SystemExit('Unexpected or repeated checksum entry')
+              if hashlib.sha256((Path('dist') / filename).read_bytes()).hexdigest() != digest:
+                  raise SystemExit('Distribution checksum mismatch')
+              checked.add(filename)
+          if checked != expected:
+              raise SystemExit('Missing distribution checksum')
+          PYVERIFY
+      - run: uvx twine check dist/*.whl dist/*.tar.gz
+      - uses: actions/upload-artifact@v6
+        with:
+          name: verified-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          name: verified-distributions
+          path: dist
+      - name: Publish verified distributions using PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

aiogram_coordination-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+coverage.json
+htmlcov/
+dist/
+build/
+site/
+.env
+.env.*
+!.env.example
+AGENTS.md
+
+.hypothesis/
+bandit-report.json
+pip-audit-report.json
+.mypy_cache/
+*.egg-info/
+.DS_Store

aiogram_coordination-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+<!-- towncrier release notes start -->
+
+## 0.1.0 (2026-11-10)
+
+### Features
+
+- Add shared task-scoped memory coordination and renewable fenced Redis coordination without Idle/Nav/Kit dependencies.
+- Normalize complete conversation identities losslessly while retaining existing canonical Redis lock hashes and caller-selected prefixes.
+- Add explicit tracked application FSM isolation, custom lease-provider receipts and renewable Redis reference isolation.
+- Revoke borrowed effect capabilities immediately when application FSM ownership is lost; preserve external cancellation and count queued scopes during shutdown.
+- Expose read-only external-session authority with immutable absolute lifetime and separate inactivity expiry.
+- Ship typed artifacts, standalone examples, compatibility CI and real-Redis concurrency/process-crash tests.

aiogram_coordination-0.1.0/CHANGES/README.rst

@@ -0,0 +1 @@
+Use feature, bugfix, doc, removal or misc Towncrier fragments.

aiogram_coordination-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,138 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [arman.avanesyan@yahoo.com](mailto:arman.avanesyan@yahoo.com). Reports should include enough context for the maintainers to assess the incident.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, or have any other concerns, please report it by contacting the project maintainers. All reports will be handled with discretion.
+
+**Contact Information**:
+- **Email**: arman.avanesyan@yahoo.com
+
+When reporting, please include:
+- Your contact information
+- Names (real, nicknames, or pseudonyms) of any individuals involved
+- Description of the incident
+- Any additional context that may be helpful
+
+## Handling reports
+
+Maintainers assess reports and may use the enforcement guidelines above. Share
+sensitive incident details by email, not public GitHub issues. This policy does
+not promise a response deadline or a separate appeals team.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+
+## Project-Specific Guidelines
+
+### For aiogram-coordination
+
+In addition to the general Code of Conduct, we have specific guidelines for our project:
+
+#### Technical Discussions
+
+- **Be constructive**: Focus on improving the code and documentation
+- **Provide context**: Include relevant code examples and error messages
+- **Be patient**: Remember that everyone is learning and contributing
+
+#### Issue and Pull Request Guidelines
+
+- **Use clear titles**: Make it easy to understand what the issue or PR is about
+- **Provide details**: Include steps to reproduce, expected behavior, and actual behavior
+- **Be responsive**: Respond to feedback and questions promptly
+
+#### Code Review
+
+- **Be respectful**: Focus on the code, not the person
+- **Be specific**: Point out exact lines and suggest improvements
+- **Be appreciative**: Acknowledge good work and improvements
+
+#### Community Support
+
+- **Help others**: Share your knowledge and experience
+- **Be inclusive**: Welcome newcomers and help them get started
+- **Be patient**: Everyone has different levels of experience
+
+## Contact
+
+For questions about this Code of Conduct or to report violations:
+
+- **Email**: arman.avanesyan@yahoo.com

aiogram_coordination-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Use Python 3.12 and uv for development; Python 3.10–3.14 are compatibility targets.
+
+```sh
+uv sync --frozen --extra redis --python 3.12
+uv run --no-sync ruff check .
+uv run --no-sync ruff format --check .
+uv run --no-sync pyright
+uv run --no-sync pytest
+uv run --no-sync mkdocs build --strict
+uv build
+uv run --no-sync twine check dist/*
+```
+
+To require real Redis tests, set `AIOGRAM_COORDINATION_REDIS_URL` to a disposable
+server and `AIOGRAM_COORDINATION_REQUIRE_REDIS=1`. Tests isolate lock prefixes and
+never flush a database. Never use a production URL. Required real-server coverage
+is at least 80%; ownership and failure assertions may not be skipped to reach it.
+
+Runtime lives in src/, tests in tests/, runnable examples in examples/, user and
+release docs in docs/, repository automation in tools/, maintained evidence in
+reports/ and changelog fragments in CHANGES/. Use feature/bugfix/doc/removal/misc
+rst fragments. Generated security/coverage JSON belongs in ignored output or CI
+artifacts. Do not commit credentials, environments or generated distributions.
+
+Preserve optional Redis and the absence of Idle/Nav/Kit imports. Describe changes,
+validation and compatibility impact in PRs. Follow CODE_OF_CONDUCT.md and report
+security concerns through SECURITY.md. Publication is a separate authorized action.

aiogram_coordination-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 aiogram-idle contributors
+Copyright (c) 2026 aiogram-coordination contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiogram_coordination-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: aiogram-coordination
+Version: 0.1.0
+Summary: Task-scoped ownership, renewable coordination and session authority contracts for aiogram
+Project-URL: Homepage, https://github.com/ArmanAvanesyan/aiogram-coordination
+Project-URL: Repository, https://github.com/ArmanAvanesyan/aiogram-coordination
+Project-URL: Issues, https://github.com/ArmanAvanesyan/aiogram-coordination/issues
+Author: aiogram-coordination contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiogram<4,>=3.22
+Provides-Extra: redis
+Requires-Dist: redis<8,>=5.0.8; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# aiogram-coordination
+
+Shared task-scoped ownership for aiogram applications and independent libraries.
+The package has no dependency on aiogram-idle, aiogram-nav or aiogram-kit.
+
+Initial alpha version: 0.1.0. Requires Python 3.10+ and aiogram 3.22–3.x.
+
+```sh
+pip install aiogram-coordination==0.1.0
+# Optional renewable Redis coordination:
+pip install 'aiogram-coordination[redis]==0.1.0'
+```
+
+## Memory coordination
+
+```python
+from aiogram_coordination import CoordinationKey, MemoryCoordinator
+
+coordinator = MemoryCoordinator()
+key = CoordinationKey("bot", bot_id=123, chat_id=42, user_id=42)
+
+
+async def protected_operation():
+    async with coordinator.hold(key):
+        scope = coordinator.scope_token(key)
+        assert scope is not None
+        # Invoke application code only while this task owns the scope.
+```
+
+Memory scopes serialize one process and one event loop. A child task does not
+inherit reentrant ownership. Identical structural conversation keys from
+independent libraries normalize to one full identity; arbitrary generic Hashable
+keys remain supported by the memory coordinator.
+
+## Existing application FSM isolation
+
+Wrap isolation explicitly when constructing the Dispatcher, not after startup:
+
+```python
+from aiogram import Dispatcher
+from aiogram.fsm.storage.memory import SimpleEventIsolation
+from aiogram_coordination import TrackedEventIsolation
+
+application_isolation = SimpleEventIsolation()
+tracked = TrackedEventIsolation(application_isolation)
+dispatcher = Dispatcher(events_isolation=tracked)
+```
+
+A custom application isolation requires an explicit `IsolationProvider` tied to
+the exact same instance. It must return a key-bound, live `LeaseHandle` and signal
+loss. Unknown opaque locks, disabled isolation and unsupported proof are rejected.
+[Custom isolation](docs/isolation.md) includes the contract and Redis reference.
+
+## Redis reference
+
+```python
+from aiogram_coordination import RenewableRedisEventIsolation, TrackedEventIsolation
+
+# application_redis is an existing redis.asyncio client owned by your app.
+application_isolation = RenewableRedisEventIsolation(redis=application_redis)
+tracked = TrackedEventIsolation(application_isolation)
+```
+
+This explicit renewable provider exposes ownership; it does not pretend to renew
+an opaque aiogram RedisEventIsolation lock. It reuses the caller's Redis client
+and public aiogram key builder. Client closure remains application-owned.
+
+Use `RedisCoordinator(redis=application_redis, prefix="application")` for fenced
+conversation storage coordination. Its default lease/renew/wait/poll/I/O limits
+are 30/10/30/0.05/5 seconds. Lost leases revoke effect authority and cancel owners.
+A Lua storage transaction must check the returned fence token and positive PTTL;
+a local ownership check cannot make an external API transactional.
+
+## External sessions
+
+`SessionAuthority.current(key)` returns an immutable `ExternalSession` or `None`.
+It reads only; it never creates, extends or clears application sessions. Outages
+raise `SessionAuthorityUnavailable` and are distinct from missing authorization.
+[Session rules](docs/sessions.md) separate immutable absolute lifetime from a
+sliding application inactivity deadline.
+
+## Compatibility and verification
+
+| Component | Supported / CI targets |
+| --- | --- |
+| Python | 3.10–3.14 |
+| aiogram | 3.22 minimum and latest resolvable 3.x |
+| Redis client | 5.0.8 minimum and latest below 8, optional |
+| Redis server | 7+ single writable primary; CI uses real Redis 7 and 8 |
+| Base install | Neither Redis nor Idle/Nav/Kit is required |
+
+CI exercises installed wheels/sdists, task isolation, real Redis renewal/loss and
+process death. [Verification evidence](reports/verification.md) distinguishes
+executed checks from configured jobs. [CONTRIBUTING.md](CONTRIBUTING.md) documents
+commands, [SECURITY.md](SECURITY.md) reporting and [release guidance](docs/releasing.md)
+the explicit tag-only publication procedure. Nothing configures logging globally
+on import. The CLI example enables only scoped development debug logging.
+
+MIT licensed; see [LICENSE](LICENSE).