crowdypy 0.4.0.dev1__tar.gz

crowdypy-0.4.0.dev1/.gitattributes

@@ -0,0 +1,8 @@
+# Normalise line endings to LF in the repository and in every working tree,
+# including Windows checkouts where core.autocrlf defaults to true.
+#
+# Load-bearing, not cosmetic: scripts/codegen.py stamps the generated modules with
+# a sha256 over the raw bytes of schema.gql and operations/**, and the vendored
+# CrowdyCPP tree is checked against a hash of its bytes. A CRLF working tree
+# produces fingerprints no other platform can reproduce.
+* text=auto eol=lf

crowdypy-0.4.0.dev1/.gitignore

@@ -0,0 +1,26 @@
+build/
+build-*/
+dist/
+wheelhouse/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.venv/
+.coverage
+coverage.xml
+htmlcov/
+*.so
+*.pyd
+*.dylib
+*.dll
+node_modules/
+.cache/
+compile_commands.json
+CMakeUserPresets.json
+.vscode/
+.idea/
+.env

crowdypy-0.4.0.dev1/.gitleaks.toml

@@ -0,0 +1,27 @@
+# gitleaks configuration: the default ruleset plus an allowlist for the classes
+# of string that are not secrets in this codebase. Same shape as the other SDKs'
+# (2026-09-08). A NEW allowlist entry is a reviewed decision -- say in the PR why
+# the string cannot be a live credential.
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Test fixtures, generated output, vendored sources, and benchmark tokens"
+paths = [
+  # Specs and fixtures: fake tokens with the right shape are the point of them.
+  '''(^|/)test_[^/]*\.py$''',
+  '''\.(spec|test)\.(ts|tsx|mts|mjs|js|cpp|sh)$''',
+  '''(^|/)(test|tests|__tests__|fixtures)/''',
+  # Benchmarks sign with a fixed, obviously fake 64-octet token.
+  '''(^|/)benchmarks/''',
+  # Generated / vendored output that is never a place a credential is written.
+  '''(^|/)dist/''',
+  '''(^|/)wheelhouse/''',
+  '''(^|/)vendor/''',
+  # Documented placeholders.
+  '''(^|/)example\.env$''',
+]
+regexes = [
+  # Tailscale addresses are not secrets.
+  '''\b100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\.[0-9]{1,3}\.[0-9]{1,3}\b''',
+]

crowdypy-0.4.0.dev1/AGENTS.md

@@ -0,0 +1,145 @@
+# CrowdyPy agent guidance
+
+CrowdyPy is the public Python SDK for Crowded Kingdoms. Its API surface follows CrowdyJS
+(the flagship) the way CrowdyCPP does; its replication hot path is CrowdyCPP's native core,
+vendored and bound with nanobind. Trust the code over this file when they disagree, then fix
+this file.
+
+## Branches and tiers
+
+GitHub default is **`prod`**. Work lands on `dev` through a pull request; `test` and `prod`
+take merge-forward promotions (`dev` -> `test` -> `prod`) that an admin merges. Nobody can
+push to the three branches directly, the admin included (`GH013: Repository rule violations
+found` is the rule working). Dependabot targets `dev`.
+
+**TIER ALIGNMENT (hard rule).** A CrowdyPy branch may only pin CrowdyJS and CrowdyCPP
+commits that exist on the **same** tier branch of those repos (`dev`<->`dev`,
+`test`<->`test`, `prod`<->`prod`). `scripts/ci/check_pin_tiers.py --from-ref` enforces it
+in CI against the pull request's base. A promotion of CrowdyPy therefore waits for CrowdyJS
+and then CrowdyCPP to reach that tier with the pinned commits.
+
+**Identity surface.** A PR that touches the paths CODEOWNERS lists under `src/crowdypy/`
+(auth, portal, pkce, session, auth_state, and their generated `_sync` twins) runs the Cursor
+`security-review` subagent first, and the PR body carries its findings.
+
+**Public repository.** Nothing internal goes in: no internal repository names, hostnames,
+ports or environment variables. `scripts/ci/check_content_policy.py` scans the tree and the
+built wheels and sdist against a denylist. Of the replication server, only the wire format
+and the client authentication sequence are public.
+
+## Layout
+
+| Path | What it is | Edit? |
+|---|---|---|
+| `src/crowdypy/` | the async source: client, transport, domains, replication, World Stores, kit, exec gateway, subscriptions | yes |
+| `src/crowdypy/studio/` | headless Crowdy Studio; asyncio only, so `scripts/unasync.py` leaves it out | yes |
+| `src/crowdypy/player_host/` | player-host observation; `schemas.v1.json` in it is CrowdyJS's, from `tools/fixtures/player_host.mjs` | yes, not the JSON |
+| `src/crowdypy/_sync/` | the blocking client, generated by `scripts/unasync.py` | never |
+| `src/crowdypy/_generated/` | operations, enums and input structs, from `scripts/codegen.py` | never |
+| `src/crowdypy/_default_origin.py` | the tier's default API origin (below) | never |
+| `native/` | the nanobind extension `crowdypy._native` | yes |
+| `vendor/CrowdyCPP/` | the pinned CrowdyCPP subset, `scripts/vendor_crowdycpp.py` | never |
+| `schema.gql`, `operations/` | CrowdyJS's, at the pin, `scripts/schema_sync.py` | never |
+| `tools/parity/` | the parity gate and its reviewed classifications | classifications |
+| `tests/fixtures/` | shared fixtures copied from CrowdyJS at the pin, and `player-host.v1.json` (CrowdyJS's verdicts, from `tools/fixtures/player_host.mjs`) | never |
+
+## Pins
+
+`pyproject.toml` records everything this tree was made against: `[tool.crowdypy.crowdyjs]`
+(version and commit), `[tool.crowdypy.crowdycpp]` (version, tag, commit and the sha256 of
+the vendored tree), `[tool.crowdypy.graphql]` (hashes of `schema.gql` and `operations/`) and
+`[tool.crowdypy.published-sdl]`. CI re-derives each from the pinned commit, so a hand edit
+anywhere downstream of a pin fails.
+
+Moving the CrowdyJS pin (it must be on the same tier branch):
+
+```bash
+python scripts/schema_sync.py --crowdyjs ../CrowdyJS --ref <commit>   # schema, operations, pin
+python scripts/codegen.py && python scripts/unasync.py
+python tools/parity/parity.py --crowdyjs ../CrowdyJS --write docs/parity-matrix.md --strict
+```
+
+then port what changed, refresh `tests/fixtures/` from the same commit, and classify or
+cover every new difference. Build CrowdyJS at the new pin (`npm ci && npm run build`) and run
+`node tools/fixtures/player_host.mjs ../CrowdyJS`: it rewrites the player-host schemas and
+their fixture, and `tests/unit/test_player_host.py` refuses either one from another commit. Moving the CrowdyCPP pin:
+
+```bash
+python scripts/vendor_crowdycpp.py --crowdycpp ../CrowdyCPP --ref <tier>/vX.Y.Z
+```
+
+CrowdyCPP's own CrowdyJS pin must equal CrowdyPy's (`--check` refuses otherwise).
+
+## The default origin
+
+`src/crowdypy/_default_origin.py` is generated per tier by the operator tooling and never
+hand-edited: `dev` declares `dev`, `test` declares `test`, `prod` declares `prod`, so a
+client built with no origin dials the tier its wheel was released for. **A promotion can
+rewrite this file with no conflict and no mention**: git resolves a one-sided change
+silently, so a clean `dev` -> `test` merge can carry `dev` onto `test`. Regenerate it for
+the destination tier after every promotion. CI's `scripts/ci/assert_default_origin.py
+--from-ref` judges the pull request base, the release guard judges the tag's tier, and the
+release re-reads the published wheel.
+
+## Gates
+
+CI (`.github/workflows/ci.yml`) runs all of these; run them before pushing:
+
+```bash
+ruff check . && ruff format --check . && mypy
+pytest tests/unit
+python scripts/vendor_crowdycpp.py --check
+python scripts/schema_sync.py --check
+python scripts/codegen.py --check
+python scripts/unasync.py --check
+python tools/parity/parity.py --crowdyjs ../CrowdyJS --check docs/parity-matrix.md --strict
+python scripts/ci/check_content_policy.py
+python scripts/ci/check_pin_tiers.py --crowdyjs ../CrowdyJS --crowdycpp ../CrowdyCPP --tier dev
+```
+
+The parity gate is **strict** (since 0.4.0): every difference from CrowdyJS carries a
+reviewed classification (`native-equivalent` or `browser-exclusion`), a stale or missing one
+fails, and a `portable-gap` fails the build. Something new in CrowdyJS that CrowdyPy lacks is
+ported in the same change that moves the pin; it is not parked as a gap.
+
+## Live e2e
+
+`tests/e2e/` holds black-box suites over the `CROWDY_E2E_*` variables CrowdyCPP's suites read;
+unconfigured they skip. Run them against the local stack and then the dev tier before a
+release moves on, and record the run in `docs/e2e-coverage.md` (configuration, the
+`tools/e2e/provision.py` helper and where each tier's org admin credentials live are there).
+
+## Releasing
+
+The version lives in six places that `tests/unit/test_release_versions.py` holds together:
+`[project].version`, `src/crowdypy/_version.py`, `uv.lock` (run `uv lock`), the README's
+first `**vX.Y.Z` line, the first `## X.Y.Z` heading of `MIGRATION.md`, and
+`docs/compatibility.md`. The branch always carries the bare `X.Y.Z`.
+
+Merge to the tier branch, then tag the merge commit: `git tag -a dev/vX.Y.Z -m "CrowdyPy dev
+vX.Y.Z" && git push origin dev/vX.Y.Z`. `release.yml` refuses a tag outside the branch it
+names, a tag that is not the tree's version, and a default origin for another tier; then it
+builds every wheel and the sdist, scans them, publishes `X.Y.Z.devN` (dev), `X.Y.ZrcN` (test)
+or `X.Y.Z` (prod) to PyPI by trusted publishing, downloads the published wheel back to read
+its origin again, and creates the GitHub release with the same files. PyPI publishing runs
+only when the repository variable `PYPI_PUBLISHING` is `enabled`, which the operator sets
+once the PyPI trusted publisher (workflow `release.yml`, environment `pypi`) is registered.
+
+Merging a PR from the command line: `gh pr merge` fails its preflight on this org, so use
+`gh api -X PUT repos/CrowdedKingdoms/CrowdyPy/pulls/<n>/merge -f merge_method=merge`.
+
+## Performance rules for the native binding
+
+The replication system saturates the local network stack, so the binding
+(`native/replication_binding.cpp`, `src/crowdypy/replication.py`) is held to these:
+
+- No Python runs per datagram: receive, HMAC verify, decode and queueing stay in CrowdyCPP's
+  thread, and Python receives batches.
+- The network thread never takes the GIL. Anything it needs from Python (assignment, token
+  refresh) is requested through a queue another thread serves, and it waits on a native
+  condition, not on the interpreter.
+- Sends are batched, and the GIL is released while a batch is encoded and sent.
+- An asyncio loop is woken through `Config::onEventsReady` and a socket pair, never by a
+  sleep-poll.
+- Every change to the hot path reruns `benchmarks/bench_replication.py` and CrowdyCPP's
+  `bench_send` on the same machine, and updates `benchmarks/README.md`.

crowdypy-0.4.0.dev1/CMakeLists.txt

@@ -0,0 +1,78 @@
+cmake_minimum_required(VERSION 3.22...4.2)
+project(crowdypy LANGUAGES C CXX)
+
+if(NOT SKBUILD)
+  message(WARNING
+    "CrowdyPy's extension is built by scikit-build-core: run `pip install .` or "
+    "`uv sync` rather than configuring this directory by hand.")
+endif()
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+# CrowdyCPP's static libraries are linked into a shared Python module.
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+set(CMAKE_CXX_VISIBILITY_PRESET hidden)
+set(CMAKE_VISIBILITY_INLINES_HIDDEN ON)
+
+find_package(Python 3.12 REQUIRED
+  COMPONENTS Interpreter Development.Module ${SKBUILD_SABI_COMPONENT})
+find_package(nanobind CONFIG REQUIRED)
+
+# A release wheel carries its own libcrypto: a user's system or Python may ship any OpenSSL
+# (or none), and the replication core signs every datagram with it. Release builds point
+# OPENSSL_ROOT_DIR at scripts/ci/build_openssl.sh's prefix (vcpkg on Windows); a source
+# build without one links the system's shared libcrypto, because a distribution's static
+# libcrypto drags in whatever that distribution compiled into it.
+if(DEFINED OPENSSL_ROOT_DIR OR DEFINED ENV{OPENSSL_ROOT_DIR})
+  set(_crowdypy_static_default ON)
+else()
+  set(_crowdypy_static_default OFF)
+endif()
+option(CROWDYPY_STATIC_OPENSSL "Link libcrypto statically" ${_crowdypy_static_default})
+if(CROWDYPY_STATIC_OPENSSL)
+  set(OPENSSL_USE_STATIC_LIBS TRUE)
+  if(MSVC)
+    set(OPENSSL_MSVC_STATIC_RT FALSE)
+  endif()
+  # FindOpenSSL asks pkg-config for a static libcrypto's private dependencies; make it ask
+  # the chosen prefix rather than the system's openssl.pc.
+  if(DEFINED ENV{OPENSSL_ROOT_DIR})
+    set(ENV{PKG_CONFIG_PATH} "$ENV{OPENSSL_ROOT_DIR}/lib/pkgconfig:$ENV{PKG_CONFIG_PATH}")
+  elseif(DEFINED OPENSSL_ROOT_DIR)
+    set(ENV{PKG_CONFIG_PATH} "${OPENSSL_ROOT_DIR}/lib/pkgconfig:$ENV{PKG_CONFIG_PATH}")
+  endif()
+endif()
+message(STATUS "CrowdyPy: static libcrypto: ${CROWDYPY_STATIC_OPENSSL}")
+# Found here rather than only inside the vendored tree: imported targets are scoped to the
+# directory that created them, and the module below links OpenSSL::Crypto directly.
+find_package(OpenSSL REQUIRED COMPONENTS Crypto)
+
+add_subdirectory(vendor/CrowdyCPP EXCLUDE_FROM_ALL)
+get_directory_property(CROWDYCPP_VERSION DIRECTORY vendor/CrowdyCPP DEFINITION CrowdyCPP_VERSION)
+
+nanobind_add_module(_native
+  STABLE_ABI
+  FREE_THREADED
+  NB_STATIC
+  LTO
+  native/module.cpp
+  native/replication_binding.cpp
+  native/session_binding.cpp
+  native/wire_binding.cpp
+)
+target_include_directories(_native PRIVATE native)
+target_link_libraries(_native PRIVATE crowdy crowdy_replication crowdy_crypto_openssl OpenSSL::Crypto)
+if(WIN32)
+  target_link_libraries(_native PRIVATE ws2_32)
+endif()
+target_compile_definitions(_native PRIVATE
+  CROWDYPY_CROWDYCPP_VERSION="${CROWDYCPP_VERSION}")
+
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+  # A statically linked libcrypto must not export its symbols from the module: CPython's
+  # own _ssl/_hashlib load a shared libcrypto, and an exported copy here could interpose.
+  target_link_options(_native PRIVATE "LINKER:--exclude-libs,ALL")
+endif()
+
+install(TARGETS _native LIBRARY DESTINATION crowdypy COMPONENT python)

crowdypy-0.4.0.dev1/LICENSE

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

crowdypy-0.4.0.dev1/MIGRATION.md

@@ -0,0 +1,178 @@
+# Migration notes
+
+CrowdyPy is pre-1.0. Within a minor line, patch releases keep source compatibility; each
+new minor may change the API. Read the section for every minor you skip.
+
+## 0.4.0
+
+Headless Crowdy Studio and full CrowdyJS parity. Additive; still CrowdyJS 18.0.4 and
+CrowdyCPP 0.54.0.
+
+- **`crowdypy.studio`.**
+  - `CrowdyStudioController` is CrowdyJS's controller on asyncio, and
+    `CrowdyStudioController.for_client(client, app_id=, grid_id=)` builds one over a
+    client.
+  - Its state is an immutable `CrowdyStudioState`, replaced on every change; `subscribe`
+    to follow it. Autosave, retries and the polled surfaces are timers on the running
+    loop.
+  - A CLIENT target runs in the `broker_factory` you pass: a host for the attached CLIENT
+    half. Without one, a CLIENT run fails with a message saying so.
+  - A cancelled agent operation raises `CrowdyStudioError`, the module's error class.
+- **Studio helpers.**
+  - `StudioLayoutController` persists CrowdyJS's layout JSON.
+  - `parse_rustc_diagnostics` parses build logs.
+  - `create_crowdy_studio_starter_project`, `github_new_repository_url` and
+    `parse_client_tick_interval_ms` port their CrowdyJS namesakes.
+  - `canonical_json`, `digest_canonical_json` and `project_content_hash` compute the
+    approval digests CrowdyJS computes.
+- **The roots CrowdyCPP sends and CrowdyJS does not:**
+  - `AuthAPI.confirm_email` and `resend_confirmation_email`;
+  - `UsageAPI.org_summary`, `app_projection` and `org_projection`;
+  - `AppsAPI.compute_budget`, `set_compute_budget` and `clear_compute_budget`;
+  - `MarketplaceAPI.app_listing_versions`;
+  - CrowdyCPP's narrow `CrowdyStudioAPI` mutations: `save_project_metadata` (fields
+    left `UNCHANGED` keep their value), `save_project_files`, `set_project_archived`,
+    `set_personal_library_file_archived` and `publish_common_file`;
+  - the new `client.crowdy_studio_agent` (`CrowdyStudioAgentAPI`): provider consent,
+    model usage and the agent policy.
+- **`crowdypy.player_host`.** The typed observation contract a game implements so tooling
+  can read the player it controls:
+  - `PlayerHostAdapterV1` and the observation, capability and command types;
+  - CrowdyJS's schemas for them, generated verbatim from CrowdyJS;
+  - `validate_json_schema_value` and `assert_bounded_json_schema`, which give CrowdyJS's
+    verdict on every value;
+  - the agent error vocabulary (`CrowdyAgentError`, with CrowdyJS's message redaction).
+- **The parity gate is strict.** A portable gap fails the build.
+
+## 0.3.0
+
+The World Stores, the Game Kit, the ck-exec gateway and GraphQL subscriptions. Additive,
+except for one fix to the blocking client (the last item). Still CrowdyJS 18.0.4 and
+CrowdyCPP 0.54.0.
+
+- **World Stores** (`crowdypy.stores`, `create_world_session(game, app_id)` over a
+  connected `game.udp`) bind CrowdyCPP's `WorldSession`. `session.tick()` applies every
+  notification since the last tick to the stores natively, runs your actor's send loop and
+  reaping, and then fires your callbacks. The stores are:
+  - `self` (`LocalActorStore`: join, set and patch state, send-on-change with keyframes and
+    heartbeats, `last_ack` / `last_error` / `status`);
+  - `actors` (`RemoteActorStore`: staleness, sample history, `on_join` / `on_leave` /
+    `on_update`, native lanes filtered by `state[offset] & mask == value`, and
+    `snapshot()` columns);
+  - `chunks` (`ChunkStore`: real-time voxel merge, optimistic `set_voxel`, `ensure_around`
+    / `hydrate` from the Game API, write-back with CrowdyJS's refuse-or-retry rules, and an
+    `on_missing` worldgen hook);
+  - `errors`, `direct_inbox`, `channel_inbox` and `events`.
+
+  `HostTracker`, `SaveStateStore` and `AvatarStateStore` make their GraphQL calls from the
+  session's timers. Nothing a tick does waits on the network.
+- **Codecs** (`crowdypy.codecs`): `json_codec`, `raw_codec`, `text_codec`, and
+  `struct_codec`, which declares a fixed layout and decodes a whole lane's states at once
+  into a numpy structured array (`codec.decode_many(snapshot.state_offsets,
+  snapshot.state_data)`).
+- **`client.world(app_id).actor()`** (`WorldClient` / `ActorClient`): an actor that
+  remembers its chunk after `join`, over `client.udp`.
+- **The Game Kit** (`crowdypy.kit`, `client.kit(app_id)`):
+  - parties, guilds and chat rooms (`kit.social`);
+  - the 48-byte engine pose (`encode_engine_pose`, `engine_pose_codec`), and
+    `engine_lanes()` as native lane filters;
+  - the engine event parsers;
+  - `run_optimistic_action`.
+- **The ck-exec gateway** (`crowdypy.exec_gateway`): `client.exec.connect(app_id)` and
+  `connect_as_developer` return a connection with `call` (msgpack), `call_raw`,
+  `subscribe`, `ping` and `on_reconnect`.
+  - It redials with backoff and renews its subscriptions, and follows a `Moved` reply to
+    the new host. The frames match the platform's shared fixture.
+  - `AsyncExecConnection` runs in asyncio; `ExecConnection` is the blocking form.
+- **`GraphQLSubscriptions.for_client(client)`**: `graphql-transport-ws` subscriptions
+  authenticated as CrowdyJS's are.
+- **Fix: the blocking client raises and returns the async client's classes.** Before,
+  every class in a generated module was a copy, so `except
+  crowdypy.PortalConsentRequiredError` did not catch what `crowdypy.sync.CrowdyClient`
+  raised. A class with no async code (errors, result structs, records) is now one class in
+  both clients.
+
+## 0.2.0
+
+Native UDP replication: CrowdyCPP's connection, now at CrowdyCPP 0.54.0, bound for Python.
+Additive; still CrowdyJS 18.0.4.
+
+- **`client.udp`** has CrowdyJS's UdpAPI methods (`connect`, `disconnect`,
+  `connection_status`, every `send_*` and `send_*_and_wait`, `send_video_frame`,
+  `flush_sends`, `subscribe`), sent as signed datagrams straight to the replication
+  server the Game API assigns rather than through the GraphQL UDP proxy. Defaults per
+  message type are CrowdyJS's (actor updates: 8 chunks, exponential decay; audio and video:
+  1 chunk). Payloads are `bytes`, not base64, and sends return the sequence number.
+- **`connect(app_token)`** takes the `AppTokenResponse` from `portal.mint_app_token`; the
+  native client needs its token id and expiry as well as the token. `client.set_app_token(
+  minted)` installs one on a game client (the bearer and `client.app_token`), so
+  `connect()` can then be called without it.
+- **`*_and_wait`** resolves on the send's echo (only actor and voxel updates echo) and, as in
+  CrowdyJS, raises `CrowdyRealtimeError` with `code` set to the server's error name
+  (`UNAUTHORIZED`, ...) or to `UDP_SEQUENCE_TIMEOUT`.
+- **The connection lifecycle runs natively.** Assignment and token refresh are GraphQL
+  calls the native side asks Python to make. A proactive refresh names the current server,
+  so the socket is kept when the Game API installs the new token there. A failed
+  assignment tries endpoint re-discovery once. `move_to_datacenter` re-assigns the UDP
+  session, and `refresh_gameplay_token()` with a live connection quiesces it and resumes it
+  under the new token. `aclose()` also closes the connection.
+- **`crowdypy.replication`** is the layer underneath, for games that drive it themselves:
+  - `AsyncReplicationConnection`, and `ReplicationConnection` for code without an event
+    loop (`poll()` / `wait()`), both with a `SessionProvider` of your own.
+  - `NotificationBatch`: the events one poll drained, as zero-copy columns (numpy arrays
+    when numpy is installed, `memoryview` otherwise), or `Notification` objects one at a
+    time.
+  - `send_actor_updates` / `send_spatial_batch`: many entities in one call, with the GIL
+    released once.
+  - `stats()`, and `manual_pump=True` with `pump()`.
+- **`crowdypy.media`**: `fragment_frame`, `VideoFrameAssembler` (including `ingest_batch`
+  for a whole batch at once), `parse_video_fragment_header`, `is_newer_frame_id`.
+- **`GridScope.send.*` and `GridScope.channels.send`** check the grid box and send on
+  `client.udp`.
+- `benchmarks/` measures it against CrowdyCPP on the same machine. A batch of 200 entity
+  updates costs 1.06x CrowdyCPP's `sendActorUpdate` per entity, and Python receives two
+  million verified notifications a second in batches. See `benchmarks/README.md`.
+
+## 0.1.0
+
+The first release. CrowdyPy follows CrowdyJS 18.0.4 (the pinned commit in
+`pyproject.toml`) the way CrowdyCPP does, and runs its native core on CrowdyCPP 0.53.0.
+
+- **The client.** `AsyncCrowdyClient` (asyncio) and its generated blocking twin
+  `CrowdyClient`, one origin, the two-token model, the full CrowdyJS error hierarchy
+  (`CrowdyGraphQLError.code`, `CrowdyAppUnavailableError`, `CrowdyUserCodeFaultError`
+  with `player_fault_of`), the `WRONG_DATACENTER` move with one retry, the sticky
+  load-balancer cookie and endpoint re-discovery (`discovery_url`).
+- **Names.** Every CrowdyJS method is the snake_case of its name (`mintAppToken` ->
+  `mint_app_token`, `listConnection` -> `list_connection`); domains likewise
+  (`client.appAccess` -> `client.app_access`). `register` and `delete` keep their names.
+- **Big integers** are decimal strings on the wire, as everywhere on the platform; methods
+  accept `int` or `str` for a `BigInt` argument and send the string.
+- **Typed results where they carry credentials.** `auth.login` returns `AuthResponse` and
+  `portal.mint_app_token` / `refresh` / `exchange_code` return `AppTokenResponse`; their
+  reprs never show the token. Other results are plain `dict`s, decoded with msgspec.
+- **Inputs** are generated msgspec structs (`crowdypy.inputs`); a plain mapping keyed by the
+  GraphQL field names works too.
+- **The wire codec** (`crowdypy.wire`) is CrowdyCPP's, byte-identical to CrowdyJS's
+  serializer on the shared fixtures.
+- **Grid scope.** `client.grid(app_id, grid_id)` returns a `GridScope`: `mint_token()` (which
+  learns the grid box), `contains()` / `assert_contains()` (raising `GridScopeError`) and the
+  grid's channels. Its replication sends (`send.*`, `channels.send`) arrive with the
+  connection in 0.2.0.
+- **A response without its root field** raises `CrowdyProtocolError`, where CrowdyJS hands
+  back `undefined`.
+- **Moves stay in the estate.** A `WRONG_DATACENTER` move or a re-discovery answer is
+  followed only to a host in the current endpoint's estate (`crowdypy.estate`), since the
+  bearer token follows the move; anything else is refused and the error surfaces. CrowdyCPP
+  bounds moves the same way; CrowdyJS bounds only its relay reconnects.
+- **Licenses.** The wheels link OpenSSL statically, so the distribution is
+  `MIT AND Apache-2.0`; every license ships in the wheel's metadata.
+- **Not in a non-browser SDK** (as in CrowdyCPP): hosted browser sign-in navigation
+  (`portal.signIn`, `handleSignInCallback`, `handleAuthorizeRequest`), the Crowdy Games
+  shell bridge and bundle hosting, the Studio browser UI, the in-browser agent pane and the
+  Web Worker player runtime. `docs/parity-matrix.md` lists every exclusion with its reason.
+
+Not in 0.1.0, and listed as portable gaps in `docs/parity-matrix.md` until they landed:
+the native replication connection, video frames and traffic metrics (0.2.0); the World
+Stores, the ck-exec gateway connection, the Game Kit and the subscriptions client (0.3.0);
+the headless Studio, and the roots CrowdyCPP covers beyond CrowdyJS (0.4.0).