aiogram-idle 0.1.0__tar.gz

aiogram_idle-0.1.0/.gitattributes

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

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

@@ -0,0 +1,22 @@
+name: Bug report
+description: Report reproducible behavior in aiogram-idle.
+body:
+  - type: textarea
+    id: versions
+    attributes:
+      label: Environment
+      description: Python, aiogram-idle, aiogram and optional Redis/server versions.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Minimal code, expected behavior and actual behavior. Remove credentials and message content.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Sanitized diagnostics
+      description: Include storage backend, FSM isolation and worker configuration where relevant.

aiogram_idle-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security reporting
+    url: https://github.com/ArmanAvanesyan/aiogram-idle/blob/main/SECURITY.md
+    about: Read the reporting guidance before disclosing a vulnerability.

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

@@ -0,0 +1,17 @@
+name: Feature request
+description: Propose an aiogram-idle improvement.
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Explain the use case and current limitation.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: Describe the public behavior and alternatives considered.
+    validations:
+      required: true

aiogram_idle-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Change
+
+Describe the problem and resulting behavior. Link related issues.
+
+## Verification
+
+List the checks run and any unverified behavior. Include recovery, ownership and
+real-Redis tests when changing storage or coordination.
+
+## Checklist
+
+- [ ] Tests cover changed behavior.
+- [ ] Public API and compatibility changes are documented.
+- [ ] A `CHANGES/` fragment is included where appropriate.
+- [ ] No credentials, generated audit reports or local environment files are included.

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

@@ -0,0 +1,219 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    services:
+      redis:
+        image: redis:7-alpine
+        ports: ["6379:6379"]
+        options: --health-cmd "redis-cli ping" --health-interval 5s --health-timeout 3s --health-retries 10
+    env:
+      AIOGRAM_IDLE_REDIS_URL: redis://localhost:6379/0
+      AIOGRAM_IDLE_REQUIRE_REDIS: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - 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
+      - name: Verify standalone dependency boundary
+        run: uv run --no-sync python -c 'import importlib.util; assert importlib.util.find_spec("aiogram_nav") is None'
+      - run: uv run --no-sync pytest --cov=aiogram_idle --cov-report=term-missing
+      - run: uv run --no-sync python tools/check_version_tag.py
+      - run: uv run --no-sync towncrier build --draft --version 0.1.0
+      - run: uv build
+      - run: uv run --no-sync twine check dist/*
+      - run: uv run --no-sync python tools/check_artifacts.py dist/*.whl dist/*.tar.gz
+      - name: Compile examples without sending messages
+        run: uv run --no-sync python -m compileall -q examples
+      - name: Smoke test Redis wheel and sdist independently
+        shell: bash
+        run: |
+          for artifact in dist/*.whl dist/*.tar.gz; do
+            smoke_dir=$(mktemp -d)
+            uv venv --python 3.12 "$smoke_dir/env"
+            uv pip install --python "$smoke_dir/env/bin/python" "${artifact}[redis]"
+            cd "$smoke_dir"
+            "$smoke_dir/env/bin/python" - <<'PYREDIS'
+          import asyncio, importlib.util, os, uuid
+          from aiogram_idle.storage.redis import RedisIdleBackend
+          assert importlib.util.find_spec("aiogram_nav") is None
+          async def check():
+              backend = RedisIdleBackend.from_url(os.environ["AIOGRAM_IDLE_REDIS_URL"], prefix="artifact:" + uuid.uuid4().hex)
+              try:
+                  await backend.initialize()
+              finally:
+                  await backend.close()
+          asyncio.run(check())
+          PYREDIS
+            cd "$GITHUB_WORKSPACE"
+          done
+
+  documentation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --frozen --python 3.12
+      - run: uv run --no-sync mkdocs build --strict
+
+  security:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --frozen --extra redis --python 3.12
+      - name: Audit source security
+        if: ${{ !cancelled() }}
+        run: uv run --no-sync bandit -r src -f json -o bandit-report.json
+      - name: Audit installed dependencies
+        if: ${{ !cancelled() }}
+        run: uv run --no-sync pip-audit --skip-editable --format json --output pip-audit-report.json
+      - name: Retain security reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-reports
+          path: |
+            bandit-report.json
+            pip-audit-report.json
+          if-no-files-found: error
+
+  compatibility:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    services:
+      redis:
+        image: redis:7-alpine
+        ports: ['6379:6379']
+        options: --health-cmd "redis-cli ping" --health-interval 5s --health-timeout 3s --health-retries 10
+    env:
+      AIOGRAM_IDLE_REDIS_URL: redis://localhost:6379/0
+      AIOGRAM_IDLE_REQUIRE_REDIS: '1'
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13', '3.14']
+        aiogram: [minimum, latest]
+        exclude:
+          # aiogram 3.22 pins pydantic before Python 3.14 wheel support.
+          - python: '3.14'
+            aiogram: minimum
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --frozen --extra redis --python '${{ matrix.python }}'
+      - name: Select aiogram compatibility endpoint
+        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/demo.py --help
+
+  redis-compatibility:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        redis: ['redis:7-alpine', 'redis:8-alpine']
+        client: [minimum, latest]
+    services:
+      redis:
+        image: ${{ matrix.redis }}
+        ports: ['6379:6379']
+        options: --health-cmd "redis-cli ping" --health-interval 5s --health-timeout 3s --health-retries 10
+    env:
+      AIOGRAM_IDLE_REDIS_URL: redis://localhost:6379/0
+      AIOGRAM_IDLE_REQUIRE_REDIS: '1'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen --extra redis --python 3.12
+      - name: Select Redis client endpoint
+        shell: bash
+        run: |
+          if [ '${{ matrix.client }}' = minimum ]; then
+            uv pip install 'redis==5.0.8'
+          else
+            uv pip install --upgrade 'redis>=5.0.8,<8'
+          fi
+      - run: uv run --no-sync pytest tests/test_redis*.py
+
+  navigation-integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    defaults:
+      run:
+        working-directory: aiogram-idle
+    services:
+      redis:
+        image: redis:7-alpine
+        ports: ['6379:6379']
+        options: --health-cmd "redis-cli ping" --health-interval 5s --health-timeout 3s --health-retries 10
+    env:
+      AIOGRAM_IDLE_REDIS_URL: redis://localhost:6379/0
+      AIOGRAM_IDLE_REQUIRE_REDIS: '1'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: aiogram-idle
+      - uses: actions/checkout@v4
+        with:
+          repository: ArmanAvanesyan/aiogram-nav
+          ref: main
+          path: aiogram-nav
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: aiogram-idle/uv.lock
+      - run: uv sync --frozen --extra redis --extra nav --python 3.12
+      - run: uv run --no-sync pyright --project pyright-nav.json
+      - run: uv run --no-sync pytest tests/test_nav*.py tests/test_component*.py tests/test_effect_scope_review.py
+      - run: uv run --no-sync python examples/navigation.py --help
+
+  required:
+    if: always()
+    needs: [quality, documentation, security, compatibility, redis-compatibility, navigation-integration]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require every verification job to pass
+        env:
+          JOB_RESULTS: ${{ toJSON(needs) }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          import sys
+          outcomes = json.loads(os.environ['JOB_RESULTS'])
+          failed = {name: job['result'] for name, job in outcomes.items() if job['result'] != 'success'}
+          if failed:
+              print('Required verification did not pass:', failed)
+              sys.exit(1)
+          print('All required verification passed.')
+          PY

aiogram_idle-0.1.0/.github/workflows/nav-integration.yml

@@ -0,0 +1,54 @@
+name: Optional navigation integration
+on:
+  workflow_dispatch:
+    inputs:
+      nav_repository:
+        description: Compatible aiogram-nav GitHub repository (owner/name)
+        required: true
+        type: string
+      nav_ref:
+        description: Compatible reviewed revision
+        required: true
+        type: string
+permissions:
+  contents: read
+jobs:
+  combined:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    defaults:
+      run:
+        working-directory: aiogram-idle
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13', '3.14']
+        redis: ['redis:7-alpine']
+        include:
+          - python: '3.12'
+            redis: 'redis:8-alpine'
+    services:
+      redis:
+        image: ${{ matrix.redis }}
+        ports: ['6379:6379']
+        options: --health-cmd "redis-cli ping" --health-interval 5s --health-timeout 3s --health-retries 10
+    env:
+      AIOGRAM_IDLE_REDIS_URL: redis://localhost:6379/0
+      AIOGRAM_IDLE_REQUIRE_REDIS: '1'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: aiogram-idle
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ inputs.nav_repository }}
+          ref: ${{ inputs.nav_ref }}
+          path: aiogram-nav
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen --extra redis --extra nav --python '${{ matrix.python }}'
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: uv run --no-sync pyright --project pyright-nav.json
+      - run: uv run --no-sync pytest --cov=aiogram_idle --cov-config=coverage-nav.toml
+      - name: Check optional example CLI without sending messages
+        run: uv run --no-sync python examples/navigation.py --help

aiogram_idle-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_idle-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+*.egg-info/
+.env
+.env.*
+!.env.example
+site/
+.mypy_cache/
+.pyright/
+coverage.xml
+bandit-report.json
+pip-audit-report.json
+reports/generated/
+.DS_Store

aiogram_idle-0.1.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+<!-- towncrier release notes start -->
+
+## [0.1.0] - 2026-11-10
+
+### Miscellaneous
+
+- Align repository automation, typed distribution checks, community
+  documentation
+  and changelog fragments with the related aiogram libraries. Runtime version
+  reporting now reads the installed distribution metadata.
+
+
+### Core library
+
+- Introduce standalone conversation identity, session/activity guards, policies and typed adapter contracts.
+- Add single-process memory storage and a recoverable inactivity lifecycle.
+- Add reply, inline, command and hybrid prompt controls with aiogram dispatcher integration.
+- Include ordinary-handler and FSM examples, deterministic tests and packaging checks.
+- Add optional Redis 7+ storage, renewable distributed coordination, atomic indexes, retained operation receipts and explicit administrative index recovery.
+- Exercise real-server worker races, process crashes, lease expiry, uncertain commits, corruption and memory/Redis parity.
+- Include optional navigation integration as detailed below.
+
+### Memory and lifecycle audit fixes
+
+- Share backend coordination across runtimes and verify FSM borrowing/scope lifetimes.
+- Enforce grace deadlines during answer admission and preserve original delivery grace on recovery.
+- Serialize effect stages, preserve typed receipts and retain confirmed subeffects across retry/recovery.
+- Guard reserved business work from reentrant/public mutations and ordinary handler admission.
+- Protect pending evidence, expire administrative receipts, route namespace/bot claims and tag operation lookup results.
+- Expand automated coverage to 168 tests, including 1,000 abandoned-claim recoveries.
+
+### Redis audit fixes
+
+- Fence namespace/configuration history, storage profiles and delegated effect checkpoints atomically.
+- Prevent revoked-scope reentry and enforce shared FSM lock order and lossless Redis FSM keys.
+- Repair missing/orphan queue jobs, isolate corrupt work and bind claims/quarantine to validated snapshots.
+- Preserve unknown business-effect ledgers and validate action receipts before completion.
+- Recheck grace before delivery, order heartbeat retries and preserve external cancellation through timeouts.
+- Document backend scope contracts and explicit recovery in docs/redis-audit.md.
+
+### Optional navigation integration
+
+- Add the optional nav extra and aiogram_idle.integrations.nav projection without peer imports in either core.
+- Commit navigation/activity/deadline updates in one memory/Redis transaction with mapped sessions and acceptance counters.
+- Resolve inherited node policies, explicit activity groups and guarded touch/restart semantics.
+- Share one coordinator and combined dispatcher middleware with verified FSM borrowing and prompt-control precedence.
+- Stage Continue/Cancel/restore rendering under existing idle operations and preserve exact worker claims through recovery.
+- Park unknown/schema-incompatible recovery without resending; retain typed receipts across process exit and final-commit failure.
+- Restore temporary reply/hybrid keyboard overlays through durable background work and silence restoration sends.
+- Preserve application cancellation uncertainty in a nested business effect stage.
+- Add a runnable four-style example, standalone artifact checks and a separate optional-integration CI matrix.

aiogram_idle-0.1.0/CHANGES/README.md

@@ -0,0 +1,17 @@
+# Changelog fragments
+
+Add a short reStructuredText fragment for a user-visible change. Name it
+`<issue>.<type>.rst`, or `+<description>.<type>.rst` when no issue exists.
+Supported types are `feature`, `bugfix`, `doc`, `removal` and `misc`.
+
+Describe the resulting behavior for a library consumer. Keep internal details in
+the pull request unless they explain a compatibility or recovery constraint.
+
+Preview release notes without modifying files:
+
+```sh
+uv run --no-sync towncrier build --draft --version 0.1.0
+```
+
+Maintainers assemble the changelog as part of the documented release process;
+adding a fragment does not publish or release the package.

aiogram_idle-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of conduct
+
+Contributors and maintainers should treat each other respectfully. Discuss ideas
+and code on their merits, welcome questions and differing experience, and give
+specific, constructive feedback.
+
+Harassment, threats, discriminatory language, personal attacks and disclosure of
+someone else's private information are not acceptable in project spaces.
+
+Maintainers may edit or remove inappropriate contributions and restrict access
+when needed to protect participants. Report conduct concerns privately through
+the contact information on the [maintainer's GitHub profile](https://github.com/ArmanAvanesyan),
+sharing only the information needed to investigate. Maintainers should handle
+reports discreetly and consider context when deciding a response.

aiogram_idle-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+Explain the problem in an issue or pull request and include a minimal reproduction
+for bugs. Keep library behavior independent of a consuming bot's business flows.
+Follow the [code of conduct](CODE_OF_CONDUCT.md) and use the
+[security reporting guidance](SECURITY.md) for sensitive findings.
+
+## Development
+
+Use Python 3.10 or newer. From the checkout:
+
+```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
+```
+
+Tests requiring a real Redis server are skipped without its URL. For storage,
+recovery or coordination changes, run the required real-server suite as described
+in [testing](docs/testing.md). Use a dedicated server because tests may flush the
+script cache. Never use production Redis or real Telegram credentials in tests.
+
+Optional navigation tests require the adjacent compatible `aiogram-nav` checkout
+and `uv sync --frozen --extra nav --extra redis`. Standalone changes must continue
+working without that peer. The [navigation guide](docs/navigation.md) explains
+the separate type and coverage profiles.
+
+## Change conventions
+
+- Keep public interfaces typed and include behavior-focused regression tests.
+- Preserve operation receipts, ownership checks and uncertain-effect evidence.
+- Add a [Towncrier fragment](CHANGES/README.md) for user-visible changes.
+- Document compatibility and recovery changes alongside the public behavior.
+- Keep repository automation in `tools/`; do not commit generated audit reports,
+  build output, credentials or local environment files.
+
+See [testing](docs/testing.md), [repository tools](tools/README.md) and the
+[maintainer release process](docs/releasing.md) for verification commands.

aiogram_idle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiogram-idle 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.