This is a risk map, not an assertion that every item is a current defect. Severity reflects the impact of making a false release/correctness claim or changing the named area without its established evidence.
| Severity | Concern | Evidence | Impact | Suggested action |
|---|
| High | Local 0.1.0 wheel, sdist, and crate acceptance passed, but the authoritative complete final-SHA candidate does not exist yet | PROGRESS.md TASK-092/TASK-093, docs/project/release.md, .github/workflows/build-wheels.yml | Dirty-tree local artifacts and an older hosted wheel run cannot be published as the final synchronized candidate | After the user commits/pushes the reviewed tree, run the complete dispatch-only build once and verify its 26 distributions, sidecars, and attestations |
| High | Hosted CI, documentation, and 24 wheel lanes passed at c815339…, but that evidence predates the sdist/crate/attestation/manifest expansion | GitHub Actions runs 32228452630, 32228472756, 32228463727; PROGRESS.md TASK-082/TASK-092 | Platform/runtime machinery is proven, but the final release workflow and source bytes have changed since that SHA | Treat the runs as TASK-082 evidence only; require a successful final-SHA complete release-artifact run for TASK-092 |
| Medium | Credentialed Telegram/CDN/proxy behavior remains separately gated and environment-dependent | tests/integration/README.md, docs/faked-methods.md, .env.example | Fake-server correctness does not prove current service-side limits or every DC edge | Run only authorized narrow live gates and report not-run/blocked conditions honestly |
| Medium | Three central orchestration modules are both large and high-churn | src/miniproto/client.py, src/miniproto/media/download.py, src/miniproto/connection/sender.py | A lifecycle change can cross request, task, storage, sender, scheduler, and cleanup ownership | Require focused cancellation/fake-server/parity tests before the full suite; refactor only behind behavior-preserving tests |
| Medium | Windows ARM64 currently excludes cryptography pending upstream wheel availability | pyproject.toml, .github/workflows/build-wheels.yml | Native extension availability is more important on that platform, and fallback coverage differs from other lanes | Keep the explicit workflow expectation and remove the marker only after the tracked upstream release supplies supported wheels |
| Medium | Durable storage uses a project-owned encrypt-then-MAC construction rather than a named library AEAD primitive | src/miniproto/session/storage.py | No break is established, but custom cryptographic composition and compatibility increase audit burden | Preserve nonce/key-separation/MAC-before-decrypt invariants, obtain specialist review, and evaluate a versioned migration to a standard AEAD envelope |
| Medium | The raw API and generated reference depend on several upstream pins with different roles and versions | tools/schema/schema-metadata.json, tools/schema/schema-source-diff.json, tools/schema/rpc-errors.json | An upstream source can drift or disagree without a runtime package change | Keep offline pins authoritative, scheduled freshness informational, and review structural/prose/error diffs before regeneration |
| Low | Packet Loom is a provisional community-poll identity rather than the permanent brand | docs/project/brand.md, docs-site/src/assets/brand/concepts/README.md, docs/THOUGHTS.md | A later winner requires regenerated derivatives and screenshots | Keep the canonical asset boundary isolated and use pnpm --dir docs-site brand:build for a deliberate swap |
| Debt item | Why it exists | Where | Risk if ignored | Suggested fix |
|---|
| Large orchestration files | Alpha development concentrated cross-cutting protocol/media behavior before stable seams emerged | client.py, media/download.py, connection/sender.py | Review cost and ownership mistakes grow with each feature | Split only where tests prove a stable lifecycle boundary; do not introduce forwarding-only abstractions |
| Long-lived plan terminology | The original roadmap called the first release “v1” before it was clarified as 0.1.0 Alpha | PLAN.md, older plans/*.md | Contributors can confuse product milestone names with semantic-version stability | Treat the dated completion plan and current release docs as superseding; reconcile trackers without rewriting history |
| Broad benchmark configuration surface | Live-media experimentation records many explicit variables to make runs reproducible | .env.example, tools/bench/benchmark_live_media_limit.py | Configuration/help/docs can drift and live comparisons can become incomparable | Keep CLI-help, environment, normalized-report, and workflow-contract tests synchronized |
| No numeric coverage threshold | Quality gates prioritize behavioral protocol/parity/fake-server matrices | pyproject.toml, .github/workflows/ci.yml | A weakly exercised new branch may pass unrelated broad checks | Add targeted tests for each behavior change; consider coverage reporting only after defining exclusions for generated code |
| Full external-library comparison remains future evidence | Current benchmarks emphasize native/fallback and internal/runtime acceptance | PLAN.md, docs/guides/performance-and-benchmarks.md | Marketing can outrun reproducible comparative evidence | Keep claims limited to recorded commands until a controlled cross-library matrix exists |
The maintained-source scan found no tracked TODO, FIXME, or HACK markers under src/, rust/miniproto/src/, or tools/. Telegram RPC names containing the word TODO and cached/generated test trees are data/artifacts, not debt markers.
| Risk | Category | Evidence | Current mitigation | Gap |
|---|
| Authorization/session disclosure | Sensitive-data exposure | SECURITY.md, session/storage.py, session/strings.py | Encrypted durable domains, protected native strings, redacted representations/log helpers, import replacement checks | Process memory, direct serialization, third-party bearer formats, user logs, and copied credentials remain outside automatic protection |
| Unsafe replay after transport ambiguity | Protocol integrity | invoke.py, connection/sender.py, errors.py | Retry-safety classification and AmbiguousRpcResult | Caller-supplied retry=True can still be unsafe if the application misclassifies a write |
| Malformed hostile network input | Input validation | mtproto/codec.py, connection/framing.py, tl/codec.py | Bounded decoding, auth/padding checks, prevalidation before state mutation, fatal transport closure | New generated/native paths must retain exact validation parity and panic-free behavior |
| Custom session-storage cryptography | Cryptographic design | session/storage.py | Fresh nonce, separate derived keys, HMAC authentication verified before plaintext decode | Independent cryptographic review and a standard versioned envelope migration are not recorded |
| Credentialed CI/live tests | Secret-management boundary | .env.example, live-media-bench.yml, tests/integration/README.md | Manual/explicit gates, repository secrets, task-owned encrypted session paths, no ordinary-PR secrets | Maintainer must still review logs/artifacts and prevent untrusted workflow execution |
| Native supply/provenance | Software supply chain | pyproject.toml, Cargo.lock, release-artifact and publish workflows | Exact/locked dependencies, clean wheel install, native import, complete checksums, per-artifact GitHub attestations, protected PyPI/crates.io OIDC publication | The complete final-SHA candidate, registry publication, and immutable GitHub release are not yet produced; the older hosted platform matrix is not the publishable candidate |
| Concern | Evidence | Current symptom | Scaling risk | Suggested improvement |
|---|
| Platform-sensitive backend wins | tools/bench/benchmark_session_crypto_backends.py, CI benchmark matrix | Rust wins the recorded protected-session workload while bulk AES-GCM can favor cryptography | A machine-specific router can regress another OS/CPU/interpreter | Keep capability routing conservative and collect comparable multi-platform samples before thresholds |
| Media throughput depends on Telegram | media/download.py, benchmark_live_media_limit.py, docs/media.md | Floods, DC placement, account type, network, disk, and file shape change tails | Higher concurrency can worsen rate limits or memory without increasing throughput | Preserve byte budgets/fixed slots/pacing and compare repeated normalized live samples |
| Static reference scale | docs/reference/manifest.json, docs-site/astro.config.ts | Thousands of committed pages make Astro/Pagefind builds non-trivial | Build time and search index size rise with future layers/docs | Keep sidebar collapsed, search chunked, generated output deterministic, and docs in a dedicated CI job |
| Process-local caches/indexes | peers.py, media/download.py, media/scheduler.py | Each process owns peer/range/scheduler state | Multi-process applications do not share warm indexes or transfer budgets | Document per-process semantics; use application-level coordination if cross-process limits matter |
The 2026-08-19 repository scan used git log --since='90 days ago' --name-only and found the highest recent churn in docs/development.md (43 appearances), PROGRESS.md (43), src/miniproto/client.py (30), docs/THOUGHTS.md (27), tests/test_media_download.py (23), docs/media.md (21), and .env.example, .github/workflows/ci.yml, pyproject.toml, src/miniproto/media/download.py, tests/test_live_media_limit_benchmark.py, and tools/bench/benchmark_live_media_limit.py (20 each). Churn is a coordination signal, not proof of a bug.
| Area | Why fragile | Safe change strategy |
|---|
| Client/sender lifecycle | Pending aliases, receive tasks, reconnect, storage, update dispatch, and media pools share shutdown/cancellation boundaries | Trace the owner of every task/future/slot and test cancellation before/after each ownership transfer |
| Media download/live benchmark | Ordering, adaptive windows, flood policy, lanes, writer rollback, hashes, and reporting evolve together | Keep engine correctness separate from live tuning; test fake invokers and accounting before live comparison |
| Development/progress/workflows | Commands and claimed evidence can drift from implemented CI | Change command, CLI help, workflow contract, docs, and progress evidence in one reviewed unit |
| Schema/reference generation | Very large output magnifies one generator/source error | Review source metadata and small focused fixtures, then run deterministic full stale checks |
| Stated intent | Current reality | Resolution boundary |
|---|
| Older reports call the milestone “v1” | The approved release target is 0.1.0 Alpha and breaking changes remain expected | PLAN.md, the dated completion plan, and release docs now state the current version; older dated evidence remains historical |
| Wave 5 provides a strict documentation gate | The site, generators, tests, and progress trackers are implemented and locally verified for origin-root and /miniproto artifacts | Preserve the local evidence boundary; hosted Pages publication remains unverified until the trusted workflow runs |
Release-facing docs describe 0.1.0 Alpha | Python/Rust metadata agree on 0.1.0; local artifacts passed the canonical gate; the complete candidate/publisher are implemented but the final-SHA candidate and publication do not exist | TASK-092 owns final hosted construction; TASK-094 is ready for the maintainer’s protected external actions |
| One permanent identity should drive the final theme | The community poll is open; Packet Loom is the explicit temporary choice | Swap through the brand generator only if the maintainer reports a different winner |
| Cross-platform/free-threaded support is a premise | Hosted CI and all 24 wheel lanes passed at c815339…; the final source tree and expanded candidate workflow are newer | Preserve the successful platform evidence and rerun the complete artifact workflow from the final release SHA |
No unresolved product question blocks the prepared 0.1.0 handoff. The permanent logo result is deliberately deferred to the community poll, and the maintainer has explicitly authorized Packet Loom until a different winner is reported. The remaining release items are explicit external actions and evidence gates, not unanswered design questions.
PROGRESS.mdPLAN.mdplans/2026-08-12-v0.1.0-alpha-completion-plan.mdpyproject.tomlrust/miniproto/Cargo.tomlsrc/miniproto/client.pysrc/miniproto/media/download.pysrc/miniproto/session/storage.pytools/schema/schema-metadata.json.github/workflows/build-wheels.yml.github/workflows/publish-release.ymlSECURITY.md
miniproto