gramflux 0.1.0a1__tar.gz

gramflux-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0a1 — unreleased
+
+- Project and distribution renamed to GramFlux (`gramflux`); import with `import gramflux`.
+
+- Initial engineering alpha with explicit Telethon 1.45.0 runtime integration.
+- Official schema provenance, deterministic typed generation, JSON cross-check and diff CLI.
+- Independent bounded TL codec and reference TCP framing, with native initial handshake probe.
+- Bounded public request admission, cancellation/deadline behavior and safe error mapping.
+- GramFlux SQLite/memory session snapshots, ordered events, composable filters and streaming files.
+- Deterministic tests, opt-in identity test, local codec benchmark, documentation and CI.
+
+Not a production release candidate. Real-account authorization, message exchange,
+update recovery and media interoperability have not been verified.

gramflux-0.1.0a1/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Code of conduct
+
+Treat contributors and users respectfully. Critique code and evidence, not people.
+Harassment, discrimination, threats, doxxing and publishing others' private information
+are unacceptable. Respect account privacy and Telegram's terms.
+
+Maintainers may remove inappropriate content, restrict participation, or remove a
+contributor after considering severity and context. Report conduct concerns privately
+to the hosting project's maintainers once a private contact is configured. Do not
+publish identifying details about affected people. No dedicated conduct contact is
+configured for this unpublished engineering alpha.

gramflux-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+Start with the [architecture](docs/design/architecture.md), [roadmap](docs/roadmap.md)
+and [security model](docs/design/security-model.md). Changes should be small and
+include evidence appropriate to the behavior. Do not claim live Telegram verification
+from a controlled backend test.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+ruff check .
+ruff format --check .
+mypy src
+pytest
+python -m gramflux.tools.schema verify
+python -m build
+```
+
+`requirements-dev.lock` records the complete CPython 3.12/Linux development environment,
+without hashes. Use `pip install -r requirements-dev.lock` to reproduce that environment;
+it is not a platform-independent resolver lock. Runtime versions are also pinned in
+`requirements-runtime.lock`. Never commit session files, account data, or credentials.
+
+Schema updates are explicit:
+
+```bash
+python -m gramflux.tools.schema update /tmp/gramflux-new-schema
+python -m gramflux.tools.schema diff src/gramflux/tl/data/api.tl /tmp/gramflux-new-schema/api.tl
+```
+
+Review both snapshots' layer advertisement, all hashes, TL/JSON consistency, removals,
+changed signatures, and unsupported grammar. Copy reviewed files into `tl/data`, run
+`generate`, then `verify`, lint, typing and tests. Generated code is never hand-edited.
+Protocol preludes and bare message records have special binary semantics; parser
+acceptance is not equivalent to standalone runtime support. A backend upgrade requires
+its own schema/protocol/session interoperability review and differential regression run.
+
+For release: update version and changelog, run CI and clean wheel/sdist installs,
+review third-party notices and security scan, execute opt-in account tests using a
+dedicated authorized test account, and update `docs/release-report.md` with actual
+results. Reproduce benchmark inputs before discussing performance. Publishing a GitHub
+Release triggers `.github/workflows/publish.yml`, which validates the matching version
+tag, runs quality checks, builds distributions, and publishes them to PyPI. Configure
+a PyPI Trusted Publisher for this repository, workflow `publish.yml`, and GitHub
+environment `pypi` first. The tag must be the package version, optionally prefixed
+with `v` (for example, `v0.1.0a1`). No long-lived PyPI API token is required.
+
+Alpha interfaces may change. After 1.0 use semantic versioning, document deprecations
+and keep deprecated public APIs for at least one minor release unless security requires
+faster removal. Report private security issues using SECURITY.md.

gramflux-0.1.0a1/LICENSE

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

gramflux-0.1.0a1/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE THIRD_PARTY_NOTICES.md CONTRIBUTING.md SECURITY.md CHANGELOG.md CODE_OF_CONDUCT.md
+include requirements*.lock
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include research *.json *.txt

gramflux-0.1.0a1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: gramflux
+Version: 0.1.0a1
+Summary: Async Telegram client with independently verifiable TL schema tooling
+Author: GramFlux contributors
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: Telethon==1.45.0
+Provides-Extra: dev
+Requires-Dist: pytest==9.1.1; extra == "dev"
+Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
+Requires-Dist: hypothesis==6.170.5; extra == "dev"
+Requires-Dist: ruff==0.17.1; extra == "dev"
+Requires-Dist: mypy==2.4.0; extra == "dev"
+Requires-Dist: build==1.6.1; extra == "dev"
+Requires-Dist: pip-audit==2.10.1; extra == "dev"
+Dynamic: license-file
+
+# GramFlux
+
+An asyncio Telegram client and independently verifiable TL schema toolkit for Python 3.11+.
+
+**0.1.0a1 is an engineering alpha, not a production release candidate.** The live
+MTProto runtime is provided by **Telethon 1.45.0**; GramFlux owns its public lifecycle,
+request admission, error mapping, session format, ordered event dispatch, streaming
+file pipeline, and independent schema generator/codec. It is not yet the independent,
+higher-performance replacement described in the long-term roadmap.
+
+The design principle is: Simple by default. Powerful when needed. Correct by design.
+Fast when measured. Maintainable by architecture.
+
+## Install
+
+From a checkout:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+```
+
+Normal installation ships generated source and exact schemas; no schema download is
+required. Distribution name `gramflux` returned HTTP 404 from PyPI on 2026-10-20.
+That is a point-in-time lookup, not a reservation or trademark clearance.
+
+## Quick start
+
+Obtain your own [API credentials](https://core.telegram.org/api/obtaining_api_id)
+and follow [Telegram's API terms](https://core.telegram.org/api/terms).
+Run `python examples/login.py` to authorize a new session, then:
+
+```python
+import asyncio
+import os
+from gramflux import Client, filters
+
+
+async def main() -> None:
+    client = Client(
+        session="example",
+        api_id=int(os.environ["TELEGRAM_API_ID"]),
+        api_hash=os.environ["TELEGRAM_API_HASH"],
+    )
+
+    @client.on_message(filters.incoming & filters.text)
+    async def on_message(event):
+        print(f"Message received in chat {event.chat_id}")
+
+    async with client:
+        me = await client.get_me()
+        print(f"Authenticated as {me.id}")
+        await client.send_message("me", "Hello from GramFlux")
+        await client.run_until_disconnected()
+
+
+asyncio.run(main())
+```
+
+The context manager connects; it never prompts, logs in implicitly, or keeps the
+program alive after the context exits. Register handlers before connecting. Text is
+sent literally, without implicit Markdown parsing. Ctrl-C triggers context cleanup.
+Session files contain authentication keys; keep them private.
+
+## Feature status
+
+| Capability | Status and evidence |
+| --- | --- |
+| Official schema snapshot | 1,573 constructors + 783 methods; IDs and fields matched against official JSON |
+| Independent typed declarations | Deterministic generated dataclasses, all 1,572 non-vector constructor minimal round trips tested |
+| Independent TL codec | Primitive/property, flags, limits, malformed data and selected differential tests |
+| Raw API at runtime | Backend bindings via `gramflux.raw`, backend layer 229; no all-method live coverage claim |
+| Native TCP framing | Full/intermediate/abridged reference implementations, differential tests |
+| Native initial handshake | One real `req_pq_multi` exchange with DC 2 verified; no authorization key created by native code |
+| User codes, bot login, SRP password | Implemented using backend; controlled tests only, no account login verified |
+| SQLite and memory sessions | Own format; persistence, permissions, locking, corrupt/foreign data tests |
+| Concurrent RPC, deadlines, cancellation | Controlled backend tests; no real-account throughput measurements |
+| New/edited messages, filters | Ordered bounded dispatcher tested; gap recovery delegated to backend, not independently verified |
+| File upload/download | Streaming pipeline and boundary/interruption tests; no live transfer verified |
+| Independent encrypted runtime | Unsupported; cryptography and update reconciliation delegated to backend |
+| Proxy, CDN, resume, foreign sessions | Unsupported by the public API |
+| Production readiness / superiority | Not claimed; see [release assessment](docs/release-report.md) |
+
+Generated bindings and wire runtime use separate schema sources. Independent
+`gramflux.tl.generated.objects` values are offline-only and are rejected by `invoke`.
+Use backend-generated functions for live raw access:
+
+```python
+from gramflux.raw import functions, types
+
+users = await client.invoke(functions.users.GetUsersRequest([types.InputUserSelf()]))
+```
+
+## Development checks
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest
+python -m gramflux.tools.schema verify
+python -m build
+python -m gramflux.tools.benchmark
+```
+
+[Guides and API reference](docs/index.md) · [Architecture](docs/design/architecture.md)
+· [Compatibility](docs/design/compatibility.md) · [Contributing](CONTRIBUTING.md)
+· [Security](SECURITY.md) · [Measured benchmark](research/benchmark.json).
+The initial independent codec is slower than the backend on the recorded input;
+there is no performance superiority claim.

gramflux-0.1.0a1/README.md

@@ -0,0 +1,111 @@
+# GramFlux
+
+An asyncio Telegram client and independently verifiable TL schema toolkit for Python 3.11+.
+
+**0.1.0a1 is an engineering alpha, not a production release candidate.** The live
+MTProto runtime is provided by **Telethon 1.45.0**; GramFlux owns its public lifecycle,
+request admission, error mapping, session format, ordered event dispatch, streaming
+file pipeline, and independent schema generator/codec. It is not yet the independent,
+higher-performance replacement described in the long-term roadmap.
+
+The design principle is: Simple by default. Powerful when needed. Correct by design.
+Fast when measured. Maintainable by architecture.
+
+## Install
+
+From a checkout:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+```
+
+Normal installation ships generated source and exact schemas; no schema download is
+required. Distribution name `gramflux` returned HTTP 404 from PyPI on 2026-10-20.
+That is a point-in-time lookup, not a reservation or trademark clearance.
+
+## Quick start
+
+Obtain your own [API credentials](https://core.telegram.org/api/obtaining_api_id)
+and follow [Telegram's API terms](https://core.telegram.org/api/terms).
+Run `python examples/login.py` to authorize a new session, then:
+
+```python
+import asyncio
+import os
+from gramflux import Client, filters
+
+
+async def main() -> None:
+    client = Client(
+        session="example",
+        api_id=int(os.environ["TELEGRAM_API_ID"]),
+        api_hash=os.environ["TELEGRAM_API_HASH"],
+    )
+
+    @client.on_message(filters.incoming & filters.text)
+    async def on_message(event):
+        print(f"Message received in chat {event.chat_id}")
+
+    async with client:
+        me = await client.get_me()
+        print(f"Authenticated as {me.id}")
+        await client.send_message("me", "Hello from GramFlux")
+        await client.run_until_disconnected()
+
+
+asyncio.run(main())
+```
+
+The context manager connects; it never prompts, logs in implicitly, or keeps the
+program alive after the context exits. Register handlers before connecting. Text is
+sent literally, without implicit Markdown parsing. Ctrl-C triggers context cleanup.
+Session files contain authentication keys; keep them private.
+
+## Feature status
+
+| Capability | Status and evidence |
+| --- | --- |
+| Official schema snapshot | 1,573 constructors + 783 methods; IDs and fields matched against official JSON |
+| Independent typed declarations | Deterministic generated dataclasses, all 1,572 non-vector constructor minimal round trips tested |
+| Independent TL codec | Primitive/property, flags, limits, malformed data and selected differential tests |
+| Raw API at runtime | Backend bindings via `gramflux.raw`, backend layer 229; no all-method live coverage claim |
+| Native TCP framing | Full/intermediate/abridged reference implementations, differential tests |
+| Native initial handshake | One real `req_pq_multi` exchange with DC 2 verified; no authorization key created by native code |
+| User codes, bot login, SRP password | Implemented using backend; controlled tests only, no account login verified |
+| SQLite and memory sessions | Own format; persistence, permissions, locking, corrupt/foreign data tests |
+| Concurrent RPC, deadlines, cancellation | Controlled backend tests; no real-account throughput measurements |
+| New/edited messages, filters | Ordered bounded dispatcher tested; gap recovery delegated to backend, not independently verified |
+| File upload/download | Streaming pipeline and boundary/interruption tests; no live transfer verified |
+| Independent encrypted runtime | Unsupported; cryptography and update reconciliation delegated to backend |
+| Proxy, CDN, resume, foreign sessions | Unsupported by the public API |
+| Production readiness / superiority | Not claimed; see [release assessment](docs/release-report.md) |
+
+Generated bindings and wire runtime use separate schema sources. Independent
+`gramflux.tl.generated.objects` values are offline-only and are rejected by `invoke`.
+Use backend-generated functions for live raw access:
+
+```python
+from gramflux.raw import functions, types
+
+users = await client.invoke(functions.users.GetUsersRequest([types.InputUserSelf()]))
+```
+
+## Development checks
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest
+python -m gramflux.tools.schema verify
+python -m build
+python -m gramflux.tools.benchmark
+```
+
+[Guides and API reference](docs/index.md) · [Architecture](docs/design/architecture.md)
+· [Compatibility](docs/design/compatibility.md) · [Contributing](CONTRIBUTING.md)
+· [Security](SECURITY.md) · [Measured benchmark](research/benchmark.json).
+The initial independent codec is slower than the backend on the recorded input;
+there is no performance superiority claim.

gramflux-0.1.0a1/SECURITY.md

@@ -0,0 +1,16 @@
+# Security policy
+
+This is an unaudited engineering alpha. Do not use it for sensitive production accounts.
+The release blockers and threat model are documented in `docs/design/security-model.md`.
+
+Do not put authorization keys, session databases, phone numbers, API hashes, bot tokens,
+passwords, codes, or private messages into public issues. For a security report, use the
+hosting project's private vulnerability reporting facility once the repository is hosted.
+No private reporting address or hosted repository has yet been configured. Until one
+exists, a sensitive deployment should not rely on this project's response process.
+A public report can describe the affected component without exploit secrets or account data.
+
+Currently only the latest alpha is supported on a best-effort basis; there is no
+security support SLA. Before release, the maintainer must configure a private reporting
+channel, triage owner and advisory process. Dependency scanning does not constitute a
+cryptographic audit or guarantee absence of vulnerabilities.

gramflux-0.1.0a1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,16 @@
+# Third-party notices
+
+GramFlux's original implementation is MIT licensed. No competitor implementation
+source is vendored. Telethon is a pinned runtime dependency, distributed separately
+under MIT; its distribution retains its copyright/license notices. Its dependencies
+are pyaes (MIT), rsa (Apache-2.0) and pyasn1 (BSD-2-Clause); retain their notices when
+redistributing their distributions. This project does not relicense dependencies.
+
+Official Telegram schema definitions are preserved with provenance in
+`src/gramflux/tl/data/metadata.json`; upstream material and Telegram service use remain
+subject to their respective upstream terms. GramFlux's MIT notice is not a claim to
+exclusive rights over Telegram API definitions. Confirm redistribution obligations
+and project branding before a public stable release.
+
+Pyrogram/Hydrogram are LGPL-3.0 projects inspected for research only. Their source is
+not copied into this distribution. gotd/td is MIT licensed and is not a dependency.

gramflux-0.1.0a1/docs/api.md

@@ -0,0 +1,42 @@
+# Public API reference
+
+Import `Client`, `Config`, `LoginChallenge`, `MessageEvent`, `filters` from `gramflux`.
+Signatures and annotations are maintained in source; `python -m pydoc gramflux.client`
+shows the complete reference without a documentation build dependency.
+
+| API | Return / semantics |
+| --- | --- |
+| Client(session=None, *, api_id, api_hash, config=None, on_handler_error=None) | Client; path or async Storage; `None` uses memory |
+| async connect() / disconnect() | None; explicit lifecycle, disconnect joins cleanup even on cancellation |
+| connected | bool; local/backend connection status, not authorization |
+| async is_authorized() | bool; server authorization check |
+| async request_login_code(phone) | LoginChallenge; explicit code request |
+| async sign_in(challenge, code) | backend User; may raise PasswordRequired |
+| async check_password(password) | backend User; SRP computation off-loop |
+| async sign_in_bot(token) | backend User; refuses replacement of authorized session |
+| async get_me() | backend User; missing auth raises AuthenticationError |
+| async send_message(peer, text) | backend Message; literal text |
+| async invoke(request) | raw backend result; use gramflux.raw.functions/types and LAYER |
+| on_message(predicate=filters.all_messages, *, edited=False) | async callback decorator, registration order |
+| async run_until_disconnected() | None; wait without disconnecting on waiter cancellation |
+| async upload_file(source, *, name=None, on_progress=None) | backend InputFile or InputFileBig |
+| async send_file(peer, file, *, caption="") | backend Message |
+| async download_file(location, destination, *, size, on_progress=None) | Path for path target, None for caller stream |
+| async download_media(message, destination, *, on_progress=None) | Path; supported document/photo |
+
+`Config` is a frozen slots dataclass; defaults: request_timeout=30.0 seconds,
+max_concurrent_requests=32, event_queue_size=256, reconnect_attempts=3,
+transport="intermediate". All client calls must use one event loop.
+
+Independent offline API: `gramflux.tl.Codec(registry=None, max_bytes=16777216,
+max_vector=100000, max_depth=64)`; `encode(value, type="Object") -> bytes`,
+`decode(data, type="Object") -> object`. Generated classes are in
+`gramflux.tl.generated.objects`, named with capitalized namespace prefixes and Request
+suffix for methods. Primitive/list fields are annotated; optional fields default to
+None, optional `true` fields to False. Flags are calculated, not constructor arguments.
+Fields sharing a bit must be present together. Repr omits field values.
+
+`gramflux.tl.parser.parse(text)` returns validated Definition descriptors. Specialized
+bare MTProto records are recognized but not generated as normal boxed objects.
+`Framing` and `probe_datacenter` are independent experimental protocol utilities.
+The native probe does not establish an authenticated channel or create an auth key.

gramflux-0.1.0a1/docs/design/architecture.md

@@ -0,0 +1,57 @@
+# Architecture and implementation boundary
+
+GramFlux is currently a dependency-backed alpha. It is not an independent MTProto engine
+and is not a superficial renamed fork: no competitor implementation is vendored, and
+the schema pipeline, codec, session persistence, dispatch, request admission, file I/O
+and public lifecycle are original modules with separate tests. Independence and measurable
+advantages remain roadmap goals, not shipped claims.
+
+| Component | Responsibility |
+| --- | --- |
+| `client.py`, `config.py` | Explicit connect/auth/shutdown; typed convenience methods, deadlines, concurrency admission |
+| `backend.py`, `raw.py` | Pinned Telethon integration; sanitized RPC errors/logs, snapshot adapter, wire bindings |
+| `storage.py` | Async storage protocol, memory store, off-loop transactional SQLite, ownership lock |
+| `events.py`, `filters.py` | Bounded ordered callback queue, async handlers, composable synchronous filters |
+| `files.py` | Seekable uploads, official small/big parts, streaming downloads, progress, atomic no-overwrite paths |
+| `tl/parser.py`, `model.py`, `generator.py` | Source diagnostics, validation, deterministic typed definitions |
+| `tl/codec.py`, `generated/` | Independent bounded TL binary codec and constructor registry |
+| `mtproto/framing.py`, `probe.py` | Independently checked transport reference and native unencrypted handshake probe |
+| `tools/schema.py`, `benchmark.py` | Explicit refresh, offline verify, diff, reproducible local measurements |
+
+The live backend owns RSA/DH authorization-key creation, MTProto 2.0 encryption,
+message IDs/seqnos/session salts, containers, acknowledgments, response correlation,
+protocol resends, reconnects, migration and update pts/qts/seq recovery. GramFlux does
+not claim to independently audit these merely by depending on them. SRP computation
+uses backend primitives in a worker thread. Other backend CPU-heavy operations may
+still block the event loop; benchmark/audit work is outstanding.
+
+The client creates one child task per admitted operation. Timeout includes semaphore
+admission, cancellation propagates to that operation, and disconnect cancels admitted
+operations before closing the backend and persisting state. Waiting callers recheck
+lifecycle state after admission. No broad application RPC retry is configured. At most
+two additional attempts are allowed for explicit preauthorization code/bot/password
+operations rejected with a migration response after the pinned backend switches DC.
+Network ambiguity does not authorize creating another send-message request.
+
+Dispatcher callbacks run one at a time in registration order. A failure is reported
+without exception contents and later handlers still receive that event. Full queues
+block producers. This does **not** bound Telethon's internal update queue; a slow
+consumer can still accumulate upstream updates. End-to-end bounded update buffering,
+durable event delivery and application-level deduplication are release blockers.
+
+SQLite saves auth/DC and backend update-state snapshots. Entity/access-hash caches
+are in-memory only. State is synchronized to disk on auth changes and clean disconnect;
+there is no crash-consistent update cursor/durable callback transaction. SQLite methods
+run off-loop; cancelled workers are joined before releasing their lifetime lock.
+
+Independent generated declarations use the source page advertised as layer 225.
+The backend's runtime uses layer 229. `Client.invoke` only accepts backend TLRequest
+instances. Joining those two schema universes without negotiated-layer validation
+would be unsafe. The native probe checks nonce and envelope structure but does not
+authenticate Telegram; no keys or credentials are involved.
+
+Dependencies were selected for a functional and reviewable vertical slice rather than
+a new cryptographic implementation. There is no plugin framework, compiled extension,
+or Pydantic dependency. Storage and the backend are injectable test boundaries; the
+private `_backend` constructor argument is not a promised extension API. Native framing
+and codec are currently independent test/tool subsystems, not the live wire stack.

gramflux-0.1.0a1/docs/design/compatibility.md

@@ -0,0 +1,39 @@
+# Compatibility and coverage
+
+Actual local verification: CPython 3.12.3, Linux x86_64 (glibc 2.39). Python >=3.11
+is the declared minimum. CI is configured for Ubuntu Python 3.11–3.14; configuration
+is not evidence that these jobs have run. Persistent storage currently requires POSIX
+flock; Windows persistent sessions and full cross-platform transfers are unsupported.
+Memory-store use on Windows/macOS has not been verified here.
+
+Pinned official source: `tl/data/api.tl`, official JSON, `mtproto.tl` and `metadata.json`.
+Retrieved 2026-10-20. Advertised page layer: **225**. API TL SHA256:
+`13d9c9f4a4ecc7282725b5a558f719cea5af0c3bafcf62531cac3a18bfaca046`.
+Generated independent declarations: **1,573 constructors, 783 methods**, all IDs and
+fields cross-checked against retained official JSON. The polymorphic vector constructor
+has specialized codec semantics; 1,572 other constructor minimal shapes round-trip.
+That is not exhaustive flag combinations, all possible objects or live method coverage.
+Protocol parser verifies 46 explicit-ID declarations; primitive/vector preludes and
+bare message records are special cases. Independent protocol object generation and
+bare-type serialization are not advertised as supported runtime features.
+
+Runtime: Telethon **1.45.0**, generated layer **229**, imported via `gramflux.raw`.
+Different source provenance/layer from independent output is intentional and visible.
+Neither runtime binding count nor generator count proves Telegram accepts every method.
+Independent declarations cannot be passed to Client.invoke. No live account test has
+run; the credential-free native initial handshake probe is the only Telegram wire
+exchange verified in this environment.
+
+| Area | Coverage boundary |
+| --- | --- |
+| High-level client | get_me, literal send_message, explicit code/password/bot auth, raw invoke, upload/send_file, document/photo download |
+| Events | New/edited messages; text/direction/chat/sender/regex filters; serialized callbacks |
+| State recovery | Backend pts/qts/seq handling; own snapshot persists clean-shutdown state, no durable event journal |
+| Transports | Backend full/intermediate/abridged TCP; independent framing checked separately |
+| Media | Seekable binary uploads up to 4000 512-KiB parts, empty upload rejected; explicit-size downloads; no CDN/parallel/resume/cross-DC file retry |
+| Errors | GramFlux sanitized RPC/auth/wait/migration/transport/session/serialization errors; timeout and cancellation remain asyncio/Python exceptions |
+| Session formats | GramFlux version-1 SQLite or MemoryStorage; no Telethon/Pyrogram/Hydrogram/Pyrofork file compatibility |
+| Unsupported auth | Signup, QR, passkey, email verification, special official-app SMS/payment flows |
+
+Migration guides map supported operations only. There is no drop-in compatibility
+promise. Read `docs/guides/migration.md` for behavioral differences.

gramflux-0.1.0a1/docs/design/competitive-analysis.md

@@ -0,0 +1,37 @@
+# Competitive research — 2026-10-20
+
+Primary sources: official project repositories, package metadata, checked-out metadata
+snapshots in `research/*-repository.json`, and `research/test-inventory.json`. File
+counts include helpers and package files, so they do not measure quality or coverage.
+No competitor performance claim is inferred from architecture. No source implementation
+was copied. Repository metadata can change; the recorded date matters.
+
+| Project | Observed maintenance | Architecture/API and dependencies | Compatibility/testing observations |
+| --- | --- | --- | --- |
+| [Telethon](https://pypi.org/project/Telethon/1.45.0/) | GitHub mirror archived; current package links to [Codeberg](https://codeberg.org/Lonami/Telethon), v1 described as maintenance mode. PyPI 1.45.0 released 2026-09-10 | asyncio TelegramClient, generated TL, Python MTProto, pyaes/rsa; optional acceleration. Familiar raw functions and high-level helpers | Package declares Python >=3.5; installed version tested here on 3.12. GitHub mirror test inventory includes crypto/RSA, helpers, events and client tests; not a current Codeberg CI audit |
+| [Pyrogram](https://github.com/pyrogram/pyrogram) | Repository archived, pushed 2024-12-23 | Decorator Client API, generated raw layer, own sessions/dispatcher, pyaes 1.6.1/pysocks 1.7.1; optional TgCrypto | setup declares ~=3.7; classifiers through 3.11 are not modern-version verification. Tests inspected include commands/HTML/file IDs; GitHub Python workflow exists |
+| [Hydrogram](https://github.com/hydrogram/hydrogram) | Not archived; pushed 2026-04-10 at inspection | Pyrogram-derived API; pyproject depends on pyaes, pysocks, aiosqlite; optional TgCrypto/uvloop | Python >=3.9, classifiers through 3.13; pytest/pytest-asyncio/Ruff development tools; API-update workflow; small test directory observed |
+| [gotd/td](https://github.com/gotd/td) | Not archived; pushed 2026-10-19 | Go, generated TL, explicit contexts, modular transport/auth/storage; substantial Go dependency graph | go.mod declares Go 1.25; hundreds of *_test.go files, benchmark/e2e/nightly/schema-update workflows. Not a Python API substitute |
+
+Limitations are contextual: Telethon's flexible high-level calls and backend retry/update
+behavior require careful policy integration; archived Pyrogram is a maintenance risk;
+Hydrogram and Pyrogram share an ecosystem/API heritage rather than GramFlux session
+compatibility; gotd requires Go. None of these observations establish GramFlux superiority.
+
+GramFlux's current differentiators are auditable official TL-vs-JSON verification,
+fail-closed schema changes, explicit admission deadlines, value-free error diagnostics,
+and a small streaming/persistence API. Their developer and performance benefits have
+not been established in user studies or server workloads. The native codec is currently
+slower on the recorded benchmark. Core networking is borrowed as a dependency, so it
+cannot support a claim of a faster independent MTProto engine.
+
+Official protocol research: [API](https://core.telegram.org/api),
+[schema](https://core.telegram.org/schema), [MTProto schema](https://core.telegram.org/schema/mtproto),
+[protocol](https://core.telegram.org/mtproto), [TL](https://core.telegram.org/mtproto/TL),
+[serialization](https://core.telegram.org/mtproto/serialize),
+[transports](https://core.telegram.org/mtproto/transports),
+[authorization](https://core.telegram.org/api/auth),
+[terms](https://core.telegram.org/api/terms),
+[credentials](https://core.telegram.org/api/obtaining_api_id).
+The official machine-readable JSON was retained as an independent check against HTML
+TL extraction, rather than substituting a competitor's schema.

gramflux-0.1.0a1/docs/design/performance-plan.md

@@ -0,0 +1,27 @@
+# Performance methodology
+
+Run `python -m gramflux.tools.benchmark --iterations 5000 --rounds 5` on an otherwise
+idle machine. JSON records Python/platform/processor, dependency versions, exact input
+shape/size, each round, median and a separately sampled tracemalloc peak. Warm-up and
+GC happen before timings. A correctness check compares bytes before measurement.
+
+The current benchmark uses one identical 64-byte inputFile constructor for GramFlux's
+independent codec and Telethon's generated codec. Both return normal objects; neither
+performs network I/O. Bounds checking and type validation differ, so these timings
+compare implemented behavior, not interchangeable security guarantees. Tracemalloc
+peaks measure traced transient allocations over a short loop, not RSS per session or
+retained heap. Results on a shared virtual machine are noisy.
+
+`research/benchmark.json` is a measured baseline, not a hard-coded competitor table.
+The independent codec is slower on this input. No optimization has been justified yet.
+Profile representative nested messages/vectors and flags before specializing encoding.
+Cache descriptors only if profiles show lookup cost, while preserving schema/version
+validation and bounds. Do not add native extensions before measuring their benefit.
+
+Not measured yet: RPC latency/throughput, multiple-session RSS, dispatch overhead,
+SQLite latency, sustained file throughput/peak RSS, reconnect recovery or Telegram
+server behavior. A fair future network comparison must use the same DC/account
+permissions, operation payload, machine, transport, retries, concurrency and conditions,
+record distributions and avoid load that violates Telegram terms. Controlled server
+fault-injection results must be separated from actual Telegram tests. File benchmarks
+must stream from disk at fixed part sizes and measure memory separately from latency.

gramflux-0.1.0a1/docs/design/security-model.md

@@ -0,0 +1,31 @@
+# Security model
+
+Assets: authorization keys, API hash, bot tokens, passwords/codes, session files,
+private messages and user-provided file destinations. Boundaries: local filesystem,
+Telegram MTProto backend, schema downloads, untrusted incoming binary objects, callbacks
+and dependencies. MTProto cloud chats are not end-to-end encrypted secret chats.
+
+| Threat | Protection | Residual risk |
+| --- | --- | --- |
+| Credential leakage | No credential repr in LoginChallenge/SessionData/native objects; sanitized RPC identifiers, backend log redaction, handler exceptions logged by type only | Python does not guarantee secret zeroization; callbacks and debuggers can expose objects; raw/backend objects may have value-bearing reprs |
+| Local session theft | POSIX mode 0600, no-follow open, regular-file validation, exclusive ownership lock, transactional SQLite snapshot | Keys are plaintext at rest; machine compromise, backups, malicious parent directory or privilege escalation compromise accounts |
+| Corrupt/foreign database | application_id and schema version checks; unrelated databases refused; version upgrades fail explicitly | No automatic repair or migration; untrusted SQLite input itself is not a sandbox |
+| Malformed TL | Bounded lengths, vector counts, depth, ID registry; unknown flags and trailing input rejected | These bounds govern independent codec only; live decoding is backend policy |
+| Resource exhaustion | Bounded admitted public RPCs and event dispatcher queue, chunked files | Backend update queues and some caches can grow; end-to-end memory bounds not established |
+| Unsafe transfer paths | Only caller-supplied destination; secure temp in destination directory; atomic no-overwrite hard-link publication; cleanup on failure | Trusted local directory required; POSIX hard-link semantics; not durable resume; no CDN support; file references may expire |
+| Event-loop blocking | SQLite/file I/O and SRP moved to threads; cancellation joins active workers | Backend key generation/other CPU code needs profiling; arbitrary user callbacks may block indefinitely |
+| Schema supply chain | Explicit HTTPS fetch with normal certificate verification, exact source/hash/date, deterministic regeneration and JSON cross-check | Hash proves snapshot identity, not upstream authenticity; no signed schema publication verified |
+| Network tampering | Established backend's MTProto implementation; native probe never accepts credentials or establishes trust | No new independent crypto audit; pinning a library is not proof of cryptographic correctness |
+| Ambiguous request outcome | No broad application retry; bounded auth-only migration retries; explicit waits/errors | Backend retransmits protocol messages during reconnect; a timeout/cancellation cannot retract a server action |
+| Interrupted shutdown | Shielded cleanup and worker joining; atomic session transaction, temporary download cleanup | SIGKILL/power loss can lose recent auth/update snapshots; callback delivery is not transactional |
+
+No encryption-at-rest feature or secrets vault is invented. Use encrypted storage provided
+by the OS and protect backups; adding application encryption requires external key
+management and another dependency/security review. Session files must not be uploaded as
+bug reports. No cross-library conversion or silent authenticated-session replacement.
+
+Runtime dependency audit is recorded in `research/dependency-audit.txt`; results apply
+only at scan time. The release still requires independent cryptographic review, live
+fault injection, memory/soak testing, verified dependency artifacts, a private security
+reporting channel, and a supported response policy. See SECURITY.md. No anti-abuse
+bypass, spam tooling, flood evasion or unauthorized login functionality is implemented.