simcord 3.2.2__tar.gz → 4.0.0__tar.gz

simcord-4.0.0/.github/workflows/dpy-master.yml

@@ -0,0 +1,25 @@
+# Early warning for discord.py internal changes: run the suite against the
+# upstream development branch every week (and on demand).
+name: discord.py master
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: |
+          uv sync --locked --extra dev --extra screenshot
+          uv pip install --no-deps -U "discord.py @ git+https://github.com/Rapptz/discord.py"
+      # Do not let project sync replace the upstream checkout with locked discord.py.
+      - run: uv run --no-sync python -m playwright install --with-deps chromium
+      - run: uv run --no-sync python -c "import discord; print(discord.__version__)"
+      - run: uv run --no-sync pytest tests examples -q

{simcord-3.2.2 → simcord-4.0.0}/.github/workflows/release.yml

@@ -89,4 +89,4 @@ jobs:
           name: dist
           path: dist/
       # Pinned to a commit SHA rather than the mutable release/v1 branch.
-      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086

{simcord-3.2.2 → simcord-4.0.0}/.github/workflows/verify.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@v7
         with:
           node-version: "24"
           cache: npm
@@ -40,6 +40,7 @@ jobs:
       - run: uv sync --locked --extra dev --extra screenshot
       - run: uv run python -m playwright install --with-deps chromium
       - run: uv run coverage run -m pytest tests examples -q
+      - run: uv run coverage combine
       - run: uv run coverage report
 
   docs:

{simcord-3.2.2 → simcord-4.0.0}/CHANGELOG.md

@@ -4,6 +4,42 @@ This changelog is generated with [towncrier](https://towncrier.readthedocs.io/).
 
 <!-- towncrier release notes start -->
 
+## 4.0.0 (2026-11-09)
+
+### Features
+
+- Add an independently recorded 184-scenario Discord behavior ledger, receipt-safe manual recorder and recovery tooling, permission-endpoint cross-checks, strict offline mismatch/stale-gap ratchets, and a generated dated evidence table. Deliberate metadata and pre-rollout REST differences remain explicitly documented rather than counted as parity.
+- Add permission explanations, structured denial details on HTTP request records and transcripts, observed-permission reports, and explicit degradation assertions. Nonthrowing history and pin-list checks contribute observed flags without inventing HTTP errors. `pytest --simcord-sweep` reruns passing function-scoped tests with authentic permission revocation, reports unhandled bot exceptions/timeouts and application assertions with source locations, and distinguishes unsupported configurations from exercised coverage, including xdist runs.
+- Project the bot's gateway cache through Discord channel obfuscation and omit hidden channels from guild REST channel listings. Role, overwrite and bot-membership changes refresh visibility; authoritative test handles retain their real data. Deferred gateway delivery retains emission-time access rather than authorizing old events against later permission changes. There is no legacy-visibility opt-out. See the permissions guide for the distinction between documented behavior and unrecorded field details.
+
+### Bug fixes
+
+- Match independently recorded Discord behavior for message payload permissions, reply/history access, reactions, pins and crossposts; archived and locked threads, creator edit authority, voice/stage text access, mentions and silent effects. Require `pin_messages` rather than `manage_messages` for bot and simulated-user pin/unpin operations. Add announcement threads and required forum tags, enforce captured validation boundaries and error trees, reject invalid timeouts and message targets, and normalize stored application commands with atomic bulk validation. See the 3.x-to-4.0 migration guide and dated behavior ledger for deliberate gaps and bot-versus-actor boundaries.
+  Keep permission reads side-effect-free during sweeps, report unsupported role-sharing transitions explicitly, preserve visible voice departures without exposing hidden destinations, and round-trip forum pin flags. Reject NSFW enabling on commands and channels while keeping unrelated previews usable; observe requested permission-dependent send effects and preserve exact Administrator permission explanations.
+  Skipped revocation lifecycles no longer count as exercised coverage, and previously captured unhandled bot failures retain precedence over skips.
+
+### Miscellaneous
+
+- Allow PyAV 17 and 18 in the optional Preview and screenshot extras, and refresh the locked media dependency to PyAV 18.1.0.
+- Repair the weekly discord.py development-branch check by installing Preview/browser dependencies and retaining the upstream SDK installation instead of resynchronizing it back to the locked release.
+
+
+## 3.3.0 (2026-11-02)
+
+### Features
+
+- Add the aware `start_time` option to `Env`, `simcord.run` and pytest markers, applying a validated UTC origin before fixtures and startup while preserving the deterministic default and elapsed time across bot restarts. Application and SQL clocks still require explicit application clock injection.
+
+### Bug fixes
+
+- Recognize discord.py's native typing interval as a virtual-only wait while preserving the initial typing request, every five-second refresh, HTTP work, and normal cancellation and lifecycle cleanup.
+- Deliver already-real-due native asyncio cancellation deadlines through blocked input during automatic clock advancement, preserving chronological resource/timer processing, strict settlement, executor ownership, and undelivered settlement failures.
+
+### Documentation
+
+- Clarify the guild-versus-DM handle scopes enforced since 3.2.1, with actionable setup errors and migration examples: use `member.user.send_dm(...)` for DM messages and `member.user` for DM slash commands, autocomplete, components, and modals. The existing `member.send_dm(...)` convenience remains supported; accepted and rejected actions are unchanged.
+
+
 ## 3.2.2 (2026-10-31)
 
 ### Bug fixes

{simcord-3.2.2 → simcord-4.0.0}/CONTRIBUTING.md

@@ -16,6 +16,13 @@ uv run ruff check src tests examples benchmarks scripts && uv run ruff format --
 uv run pyright src
 ```
 
+Coverage includes the pytest plugin's real subprocess runs. To measure the full
+suite, run `uv run coverage run -m pytest tests examples`, then
+`uv run coverage combine` before `uv run coverage report`. The
+[native subprocess patch](https://coverage.readthedocs.io/en/stable/subprocess.html)
+requires coverage.py 7.10 or newer; do not replace those lifecycle checks with
+mocked pytest calls or lower the coverage ratchet.
+
 The Python hooks run ruff on commit and pyright on push using the project's
 pinned tools. Run the frontend check below separately; passing Python hooks
 does not replace the JavaScript CI gate.
@@ -32,6 +39,10 @@ uv sync --extra dev --extra screenshot                # matches the CI lint job
 uv run playwright install --with-deps chromium        # needed once for browser capture tests + the example
 ```
 
+The weekly `discord.py master` workflow installs the same screenshot dependencies
+and Chromium before exercising upstream discord.py. After installing that checkout,
+use `uv run --no-sync` so the project lock does not replace it with the released SDK.
+
 Frontend contributors also need Node 24:
 
 ```bash

{simcord-3.2.2 → simcord-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simcord
-Version: 3.2.2
+Version: 4.0.0
 Summary: Offline discord.py bot testing with pytest. No network, token, or test server.
 Project-URL: Homepage, https://github.com/SilentHacks/simcord
 Project-URL: Documentation, https://simcord.readthedocs.io/
@@ -29,7 +29,7 @@ Requires-Dist: pytest-asyncio>=0.24; extra == 'bench'
 Requires-Dist: pytest-benchmark>=4; extra == 'bench'
 Requires-Dist: pytest>=8; extra == 'bench'
 Provides-Extra: dev
-Requires-Dist: coverage[toml]>=7; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.10; extra == 'dev'
 Requires-Dist: hypothesis>=6; extra == 'dev'
 Requires-Dist: jsonschema>=4; extra == 'dev'
 Requires-Dist: pre-commit>=3; extra == 'dev'
@@ -45,7 +45,7 @@ Requires-Dist: mkdocs-material>=9; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
 Provides-Extra: preview
 Requires-Dist: aiohttp>=3.9; extra == 'preview'
-Requires-Dist: av<17,>=14; extra == 'preview'
+Requires-Dist: av<19,>=14; extra == 'preview'
 Requires-Dist: linkify-it-py>=2.0.3; extra == 'preview'
 Requires-Dist: markdown-it-py>=4.1; extra == 'preview'
 Requires-Dist: pillow>=10; extra == 'preview'
@@ -56,7 +56,7 @@ Requires-Dist: pytest-asyncio>=0.24; extra == 'pytest'
 Requires-Dist: pytest>=8; extra == 'pytest'
 Provides-Extra: screenshot
 Requires-Dist: aiohttp>=3.9; extra == 'screenshot'
-Requires-Dist: av<17,>=14; extra == 'screenshot'
+Requires-Dist: av<19,>=14; extra == 'screenshot'
 Requires-Dist: linkify-it-py>=2.0.3; extra == 'screenshot'
 Requires-Dist: markdown-it-py>=4.1; extra == 'screenshot'
 Requires-Dist: pillow>=10; extra == 'screenshot'

{simcord-3.2.2 → simcord-4.0.0}/docs/api.md

@@ -19,6 +19,17 @@ top-level `simcord` package unless a module-qualified path is shown.
 
 ::: simcord.Env
 
+### `Env(start_time=None)`
+
+Sets the immutable initial virtual UTC instant before backend IDs, fixtures and startup.
+`None` preserves 2026-01-01 UTC. Supply an aware `datetime`; offsets normalize to UTC.
+Invalid values raise `SetupError`. Supported UTC instants are at least
+2015-01-01 00:00:00 and strictly before 2154-05-15 07:35:11.104.
+Elapsed time advances normally and survives bot restarts. `simcord.run` and
+`@pytest.mark.simcord` accept the same option. This does not synchronize application or
+SQL wall clocks; bind application time seams to `env.now` before startup when needed.
+See [time control](guides/time-control.md#choosing-the-initial-utc-instant).
+
 ### `Env(settle_timeout=5.0)`
 
 `settle_timeout` is the default maximum time spent joining runnable bot work. A direct
@@ -47,6 +58,30 @@ encoded headers; uploaded files are not captured. The `json` field preserves the
 JSON-compatible shape, including top-level arrays. `params` and `json` are detached deep
 snapshots, so later mutations to source containers do not alter a record.
 
+Permission refusals additionally populate `denial` with structured authorization
+detail; successful requests leave it `None`. This diagnostic is separate from the
+authentic Discord error body.
+
+### Permission diagnostics
+
+`Env.explain_permissions(actor, channel)` returns a JSON-friendly mapping with
+`actor_id`, `guild_id`, the requested `channel_id`, `permission_channel_id`,
+ordered `steps`, and final integer `effective` bits. Each step includes `source`,
+`before`, `allow`, `deny` and `after`, satisfying `after = (before & ~deny) | allow`;
+roles and overwrites include their target identifiers. Administrator resets to the
+canonical all-permissions mask, discarding unknown bits. Thread explanations resolve
+inherited parent overwrites.
+
+`Env.permission_checks` is a detached snapshot of bot authorization checks.
+`Env.observed_permissions()` returns a `discord.Permissions` union of exercised
+flags, including denied checks and nonthrowing checks for requested send effects:
+enabled TTS, known external emoji references, and policy-permitted mass mentions
+or unmentionable role pings. Refused effects still degrade successfully and do not
+populate a successful request's `denial`. Plain text, suppressed mentions, and DMs
+do not add irrelevant guild effect flags. This reports exercised paths, not the
+permissions needed by every possible bot execution. See
+[permission diagnostics](guides/diagnostics.md#permission-diagnostics).
+
 ## Builders
 
 Synchronous, omnipotent handles for arranging the virtual Discord. Returned by `env`/`guild`

{simcord-3.2.2 → simcord-4.0.0}/docs/guides/components.md

@@ -26,9 +26,25 @@ inspect remote media dimensions or contents.
 
 Nested buttons and selects dispatch through their real discord.py callbacks. The same
 `click`, `select`, and `submit_modal` methods are available on `UserHandle` for component
-flows in DMs. Use `component_text=` and `component_custom_id=` with `assert_message`,
-`assert_sent`, or `assert_responded` to inspect layouts without treating TextDisplay text
-as legacy message content.
+flows in DMs. Since 3.2.1, use `member.user` for these DM actions rather than the
+guild-scoped `MemberActor`:
+
+```python
+opened = await alice.user.click(dm_message, custom_id="feedback:open")
+submitted = await alice.user.submit_modal(opened, {"comment": "Great bot"})
+# For a DM select menu:
+selected = await alice.user.select(dm_menu, ["green"], custom_id="color")
+```
+
+DM callbacks receive SDK interactions with `interaction.guild is None`. Keep using
+`alice.click(...)`, `alice.select(...)`, and `alice.submit_modal(...)` for interactions in
+`alice`'s guild. A `UserHandle` cannot act on guild messages; use a `MemberActor` belonging
+to the target guild instead. These are SimCord handle scopes, not limitations on what the
+same human can do in Discord.
+
+Use `component_text=` and `component_custom_id=` with `assert_message`, `assert_sent`,
+or `assert_responded` to inspect layouts without treating TextDisplay text as legacy
+message content.
 
 ## Clicking buttons
 

{simcord-3.2.2 → simcord-4.0.0}/docs/guides/diagnostics.md

@@ -131,14 +131,131 @@ assert len(posts) == 1
 assert posts[0].json["content"] == "Pong!"
 ```
 
-Each record exposes `method`, `path`, `params`, `json`, and `reason`. These values are the
-arguments discord.py passed to its transport: query parameters are not wire-normalized
+Each record exposes `method`, `path`, `params`, `json`, `reason`, and `denial`.
+Transport arguments retain discord.py's values: query parameters are not wire-normalized
 strings, and `reason` is not an encoded HTTP header value. Uploaded files are not captured.
 The `json` field preserves every supplied JSON-compatible shape, including top-level arrays.
 `params` and `json` are detached deep snapshots, so later mutations to source containers do
 not alter a record. The request record is appended before fault injection and route handling,
 so failed and unimplemented requests remain observable.
 
+## Permission diagnostics
+
+Explain effective permission bits independently of a failed operation:
+
+```python
+trace = simcord_env.explain_permissions(simcord_env.bot.user, channel)
+effective = discord.Permissions(trace["effective"])
+for step in trace["steps"]:
+    print(step["source"], step["before"], step["after"])
+```
+
+The ordered trace covers base roles, owner/Administrator bypasses, `@everyone`,
+aggregated role and member overwrites, and active timeout masking. Threads use
+their parent's overwrites. This explains permission bits, not every REST policy:
+thread state, channel access and role hierarchy can independently refuse an action.
+
+Bot refusals add `DENIAL` entries to the transcript and structured `denial` detail
+to the failing HTTP request record. Discord exception text and error JSON remain
+unchanged. `env.permission_checks` returns detached check records with actor,
+guild and channel IDs, required/missing flags, effective bits, outcome and reason.
+Non-permission authorization refusals, such as role hierarchy, are attributed too.
+
+```python
+observed = simcord_env.observed_permissions()
+print([name for name, used in observed if used])
+```
+
+Observed flags include refused checks. They describe only paths this environment
+exercised, not a least-privilege guarantee for your entire bot.
+Implicit guild-channel access contributes `view_channel` (reported as
+`read_messages` when iterating discord.py's native permissions). DM checks do not
+invent guild permission requirements.
+History and pin listings also record their nonthrowing `read_message_history`
+checks. Without that permission, the listings still succeed with an empty result;
+the check is refused, but no HTTP exception or request denial is invented.
+
+### Silent degradations
+
+Some successful requests lose an effect without a Discord error:
+
+```python
+for degradation in simcord_env.degradations:
+    print(degradation["kind"])
+simcord_env.assert_no_degradations()  # opt-in assertion
+```
+
+Records are detached snapshots. Modeled ordinary-send cases are missing TTS
+permission (`tts_permission_dropped`), unmentionable role pings
+(`unmentionable_role_ping_dropped`), ignored ephemeral flags
+(`normal_message_ephemeral_ignored`) and known external custom emojis without
+the external-emoji permission (`external_emoji_permission_stripped`).
+An explicit allowed-mentions policy suppressing a ping is intentional, not a
+degradation. Unknown emoji IDs are not guessed or rewritten. Successful TTS
+creates retain `tts=True` in the create result/event but ordinary bot messages
+read later have `tts=False`, matching the captured behavior.
+
+### Suite reports and failure sweeps
+
+```bash
+pytest --simcord-observed-permissions
+pytest --simcord-sweep
+```
+
+The observed-permissions option aggregates exercised flags across environments
+and xdist workers. The sweep first runs each test normally, then reruns passing
+tests with fresh function-scoped fixtures once per observed permission.
+It discovers both `simcord_env` and environments created directly or through
+`simcord.run`.
+
+Revocation changes real bot-exclusive roles and bot member overwrites, not HTTP
+fault responses. REST enforcement, interaction `app_permissions` and cached
+`channel.permissions_for(guild.me)` therefore agree. A channel overwrite can
+revoke a channel permission while `guild.me.guild_permissions` correctly retains
+the guild-level grant.
+
+Existing worlds are projected once when registered. Canonical builder and REST
+permission mutations project the affected guild/channel before returning models,
+serializing responses or publishing events, including silent construction.
+Permission reads never project, mutate state or emit events. Raw model/dictionary
+permission writes are unsupported; use the builder or backend mutation methods.
+
+Test-driver assertions that no longer hold under revocation are ignored.
+Assertions raised by application code are findings, like other unhandled bot
+exceptions and timeouts, and are reported with the permission and source location;
+findings make pytest exit unsuccessfully. Handled refusals are not findings.
+Baseline failures remain ordinary test failures and are not swept.
+
+Successful custom event, prefix-command, application-command, View and Modal
+error handlers consume their errors for sweep purposes. A handler that raises
+or reraises still produces a finding. Routed errors remain in `Env.errors` for
+normal diagnostics and its existing assertion policy; the sweep distinguishes
+those observations from unhandled runtime failures.
+
+Env-owned callback/task errors and settlement timeouts carry bot-ownership
+evidence. Direct product calls can also produce findings when their traceback
+reaches application code under pytest's root, outside the configured `testpaths`.
+Keep test helpers under those test paths: a direct SDK helper refusal, or a
+failure without application ownership evidence, is unsupported rather than an
+invented bot failure. Broader external application code is still covered when
+executed as Env-owned bot work. A baseline using only permissionless interaction
+callbacks may observe no flags; that is not permission-revocation coverage.
+
+The report separates exercised and unsupported cases. Broader-scoped user
+fixtures, reused environments, bot-owned guilds, Administrator bypasses,
+and guild-scoped grants that cannot be removed without changing other members
+are unsupported. Removing Administrator could revoke unrelated permissions, so
+it is never presented as a faithful one-flag sweep. Sharing a role after its
+guild-scoped grant was suppressed restores that owned bit and stops the rerun
+as unsupported; pytest still tears down its fixtures. Explicit later permission
+edits relinquish ownership of the old suppressed bit; unrelated role/overwrite
+edits are retained. No roles are cloned and no whole-world rollback is used.
+Harness/setup failures are unsupported rather than invented bot failures.
+Skipped revocation setup or test calls are unsupported, not exercised coverage;
+any already-captured unhandled bot errors remain findings.
+An unsupported case is not evidence that your bot handles revocation.
+Missing xdist worker reports explicitly mark coverage incomplete.
+
 ## Injecting API failures
 
 Real bots have to survive Discord hiccups. `env.inject_error` makes matching REST calls fail

{simcord-3.2.2 → simcord-4.0.0}/docs/guides/fixtures.md

@@ -100,6 +100,7 @@ Both `simcord.run(bot, **options)` and the underlying `Env` accept these keyword
 | `approved_intents` | `None` (all approved) | Simulates developer-portal privileged-intent toggles and REST Message Content access, independently of the Gateway request bit. Explicit `Intents.none()` denies approval. |
 | `shard_count` | client setting | Supplies the Get Gateway Bot recommendation when an `AutoShardedClient` does not configure `shard_count` itself. |
 | `settle_timeout` | `5.0` seconds | Default maximum time for joining runnable bot work; a direct settle `timeout=` overrides it. |
+| `start_time` | `None` (2026-01-01 UTC) | Aware initial UTC instant, normalized from any offset before fixtures/startup; see [time control](time-control.md#choosing-the-initial-utc-instant) for supported bounds and application clock wiring. |
 
 `settle_timeout` does not change startup's fixed five-second READY settlement budget.
 Restart drains existing work using `settle_timeout`, then gets a fresh fixed five-second
@@ -181,6 +182,20 @@ async def test_command_logic_in_isolation(simcord_env):
     ...
 ```
 
+The same marker accepts an initial clock origin:
+
+```python
+from datetime import UTC, datetime
+
+@pytest.mark.simcord(start_time=datetime(2030, 4, 5, tzinfo=UTC))
+async def test_future_entitlement(simcord_env):
+    assert simcord_env.now() == datetime(2030, 4, 5, tzinfo=UTC)
+```
+
+For application clock injection needed by `setup_hook`, construct `Env` and bind
+`env.now` before manual startup in your fixture; the
+[time-control example](time-control.md#choosing-the-initial-utc-instant) includes teardown.
+
 In 3.0, error snapshots with prefix acknowledgement and detached mutable result
 payloads are unconditional. Remove the temporary 2.3 `future_behavior` marker/run
 option; see [Migration](../stability.md#migrating-from-23-to-30).

{simcord-3.2.2 → simcord-4.0.0}/docs/guides/permissions.md

@@ -61,8 +61,12 @@ state and cross-guild role/member targets are rejected before channel creation.
   (`50013`). It also can't delete the `@everyone` role.
 - **Editing others' messages** — the bot can't edit another user's message (`50005`).
 - **Timeouts** — a timed-out member loses everything except viewing and reading history.
-- **Reactions** — `add_reactions` is required to introduce a new emoji, not to join an
-  existing reaction. Both require access to the message and its history.
+- **Bot reactions** — `add_reactions` is required to introduce a new emoji, not
+  to join an existing reaction or remove your own. Read Message History is not
+  required on these bot REST paths. Simulated users and Preview retain their
+  separate history-access checks.
+- **Pins** — pinning and unpinning require `pin_messages`, for both bots and
+  simulated users. `manage_messages` does not grant this permission.
 
 ```python
 async def test_cannot_ban_higher_role(simcord_env):
@@ -81,6 +85,74 @@ async def test_cannot_ban_higher_role(simcord_env):
     assert guild.get_ban(boss) is None
 ```
 
+## Bot-visible channels
+
+The bot's cache follows Discord's [channel-obfuscation contract](https://docs.discord.com/developers/resources/channel#channel-object-obfuscated-channels):
+channels it cannot view have the name `___hidden___`, the obfuscated flag, neutral
+sensitive fields and a synthetic `@everyone` overwrite denying `view_channel`.
+Guild channel listings omit those channels; fetching one directly is denied.
+Role and overwrite changes update this projection, including threads under a
+hidden parent. Categories remain visible when a child is visible, and a connected
+voice channel remains visible to the bot.
+
+Builders, actors and backend state retain their authoritative data. Use a
+`ChannelHandle` to inspect test setup, not the bot cache. Interaction wire payloads
+remain unobfuscated; discord.py 2.7.1 may nevertheless resolve `Interaction.channel`
+from its existing cache, and does not expose the wire obfuscation flag on every
+channel class.
+
+Our [live evidence](../parity-matrix.md#behavior-evidence) includes opt-in gateway
+captures for text, voice, forum and category channels. Structural fields such as
+slowmode and voice limits are retained. REST list filtering follows Discord's
+documented mandatory behavior; it was not yet enforced in the dated live capture
+and is an explicit known gap, not a claim of matching that pre-rollout response.
+Uncaptured neutral-field details and category/voice visibility edge rules remain
+documented simulator policy.
+
+Visible voice occupants are projected per connection at event admission, including
+events waiting for FIFO parser delivery. Moving into a hidden channel (or losing
+visibility while stationary) clears the SDK voice cache with a departure built
+only from the last authorized snapshot and `channel_id: null`. Hidden-to-hidden
+movement discloses nothing; a reveal restores current authorized occupants.
+This departure wire shape is an intentional privacy/cache-safety inference, not
+a recorded live Discord observation. Canonical backend voice state is unchanged,
+and normal voice intent and shard routing still apply.
+
+## Bot REST behavior
+
+- Embeds, uploads and polls on ordinary messages require `embed_links`,
+  `attach_files` and `send_polls`. Replies require history (`160002`); fetching a
+  message, pinning and crossposting also check history. Listing pins without
+  history succeeds with an empty list.
+- Voice and stage text actions require `connect` (`50001`). Pinning there is
+  refused with `50019`, even when `pin_messages` is granted.
+- Archived-thread edit, delete, bulk delete, reaction and pin actions fail with
+  `50083`. Sending automatically unarchives an unlocked thread after validating
+  the payload. Locked sends need `manage_threads`; locked unarchive without it
+  fails with `160005`.
+- Thread creators may rename, archive and lock their threads; other members
+  need `manage_threads`. Edits and unarchive also need
+  `send_messages_in_threads`. **Deleting requires `manage_threads`, including
+  for the creator**, as confirmed by our own recording. Leaving needs no view
+  access.
+- Forum thread pinning and unpinning require `manage_threads`, even for the
+  creator. The pinned flag is returned consistently by edits, fetches, gateway
+  events and active/archived listings. Pinning non-forum threads and changing
+  unsupported thread flag bits are rejected before mutation; existing unrelated
+  bits are preserved.
+- NSFW channels are not modeled: channel creation/edit and thread creation reject
+  enabling NSFW. Omitted or literal `False` metadata is accepted inertly; there is
+  no way to enable NSFW.
+- `AllowedMentions` controls the returned mention arrays. Missing TTS permission,
+  unmentionable role pings, ignored ephemeral flags on normal sends and denied
+  known external custom emojis are modeled as successful requests with reduced
+  effects, reported through [`env.degradations`](diagnostics.md#silent-degradations).
+
+These bot recordings do not establish the rules for simulated human actors.
+Actor behavior is unchanged except for the documented pin-permission split and
+the docs-based locked-thread send guard.
+
+
 ## Application command visibility
 
 Before an actor dispatches a slash command, autocomplete request, or context menu, SimCord checks whether that user could see the command in that guild and channel. This is separate from callback checks such as `@app_commands.checks.has_permissions(...)`; hidden commands raise `SetupError` instead of dispatching an interaction. See [slash command visibility](testing-slash-commands.md#command-visibility) for scope/context rules, permission overrides, reason codes, and fixture setup.

{simcord-3.2.2 → simcord-4.0.0}/docs/guides/testing-slash-commands.md

@@ -90,13 +90,19 @@ uploaded = await alice.slash(channel, "upload", file=("photo.png", b"image bytes
 
 ## Bot-DM slash commands and visible command lists
 
-`UserHandle.slash(name, **options)` and `UserHandle.autocomplete(name, option, value, **filled)` invoke global commands whose contexts allow `BOT_DM`. Their interactions have `context == 1`:
+`UserHandle.slash(name, **options)` and `UserHandle.autocomplete(name, option, value, **filled)` invoke global commands whose contexts allow `BOT_DM`. Their interactions have `context == 1`, and the SDK callback receives `interaction.guild is None`:
 
 ```python
 user = simcord_env.create_user("alice")
 await user.slash("help")  # The bot's callback receives interaction.context == 1.
 ```
 
+For an existing guild member, use `await member.user.slash("help")` or
+`await member.user.autocomplete("tag", "name", "py")` for DM commands. Since 3.2.1,
+passing `member.user.dm_channel` to `member.slash(...)` or `member.autocomplete(...)`
+is rejected: `MemberActor` is guild-scoped. Keep `member.slash(channel, ...)` and
+`member.autocomplete(channel, ...)` for its guild.
+
 Use `member.available_commands(channel)` or `user.available_commands()` to get a tuple of leaf invocation strings that are visible there and accepted by `slash()` (for example, `"config set"`):
 
 ```python

{simcord-3.2.2 → simcord-4.0.0}/docs/guides/threads-reactions-dms.md

@@ -70,11 +70,32 @@ reply = alice.user.dm_channel.history()      # what the bot DM'd back
 assert reply[-1].content.startswith("Hi")
 ```
 
+`alice` above is a `MemberActor`; `alice.send_dm(...)` remains a supported convenience
+that delegates to `alice.user.send_dm(...)`. Other guild-scoped actor methods do not
+target DMs. Use the `UserHandle` (`alice.user`) for DM messages, commands, components,
+and modals; keep `alice` for operations in its guild.
+
+Since 3.2.1, migrate calls that passed a DM channel to a guild actor:
+
+```python
+# Before 3.2.1: a guild actor was used to target a DM.
+await alice.send(alice.user.dm_channel, "hello bot")
+
+# Now: send through the user's DM-scoped handle.
+await alice.user.send_dm("hello bot")
+# This existing convenience also remains supported:
+await alice.send_dm("hello bot")
+
+# Guild operations still use the guild member.
+await alice.send(channel, "hello guild")
+```
+
 `alice.user.dm_channel` is the user's DM channel with the bot; `.history()` returns the
 conversation as real `discord.Message` objects. A `UserHandle` can also invoke global slash
 commands and autocomplete in that DM when their command contexts allow `BOT_DM`; these
-interactions carry `context == 1`. Use `user.available_commands()` to list the slash invocations
-visible there. See [slash command visibility and DM commands](testing-slash-commands.md#bot-dm-slash-commands-and-visible-command-lists).
+interactions carry `context == 1` and the SDK callback receives `interaction.guild is None`.
+Use `user.available_commands()` to list the slash invocations visible there. See
+[slash command visibility and DM commands](testing-slash-commands.md#bot-dm-slash-commands-and-visible-command-lists).
 
 Guild actors can edit/delete their messages and pin with `set_pinned`. In the user's bot DM,
 `UserHandle` supports their own message edits/deletes, desired reactions, and poll votes:

{simcord-3.2.2 → simcord-4.0.0}/docs/guides/time-control.md

@@ -9,6 +9,47 @@ Time-dependent behaviour — `View` timeouts, command cooldowns, `asyncio.sleep`
 — is normally painful to test: you either wait in real time (slow, flaky) or mock the clock
 by hand (fiddly, leaky). SimCord gives you a **virtual clock** you fast-forward in one call.
 
+## Choosing the initial UTC instant
+
+`Env(bot, start_time=...)` and `simcord.run(bot, start_time=...)` accept an aware
+`datetime`. The default remains **2026-01-01 00:00:00 UTC**. Offsets normalize to UTC;
+naive datetimes, non-datetimes and unsupported instants raise `SetupError` before backend
+IDs or runtime hooks are created. The supported initial UTC range is
+**2015-01-01 00:00:00 inclusive through 2154-05-15 07:35:11.104 exclusive**.
+The origin is fixed at construction, already applies to pre-start fixtures and backend
+timestamps, and survives bot restarts along with elapsed virtual time. There is no rewind
+or `set_time` operation.
+
+Bind your application's existing clock seam **before** startup so `setup_hook` and
+fixture writes use the same clock. For example, a custom pytest fixture can use manual
+lifecycle control:
+
+```python
+from datetime import UTC, datetime
+
+import pytest_asyncio
+import simcord
+
+@pytest_asyncio.fixture
+async def world():
+    bot = create_bot()
+    env = simcord.Env(bot, start_time=datetime(2030, 4, 5, 12, tzinfo=UTC))
+    bot.service.now = env.now  # application-owned callable used by startup and writes
+    await env.start()
+    try:
+        yield env
+    finally:
+        await env.shutdown()
+```
+
+The standard pytest fixture also accepts
+`@pytest.mark.simcord(start_time=datetime(2030, 4, 5, tzinfo=UTC))`.
+Use a manual fixture when application wiring must happen before `env.start()`.
+Selecting an initial origin does **not** synchronize Python wall time, SQL
+`CURRENT_TIMESTAMP`/`now()`, database defaults or application clocks. Inject `env.now`
+through existing application time seams, including relevant persisted writes, rather
+than globally monkeypatching datetime, SQL or SDK functions.
+
 ## `env.advance_time(seconds)`
 
 ```python
@@ -35,6 +76,9 @@ Anything the bot scheduled against the loop's clock:
 - **Resource deadlines** — polls, scheduled events and explicitly scheduled entitlement ends.
 - **Supported SDK UTC helpers** — entitlement expiry, `discord.utils.sleep_until`, and
   relative/calendar `discord.ext.tasks` loops use the selected virtual clock.
+- **Typing refresh intervals** — the native SDK typing task's direct five-second sleep
+  is virtual-only. Its initial HTTP request and every refresh still execute and join
+  normally; HTTP waits and retries are not treated as parked typing intervals.
 
 ```python
 async def test_cooldown_resets(simcord_env):
@@ -109,13 +153,17 @@ and retry shutdown.
 
 ## Determinism
 
-Snowflake IDs and UTC start from a fixed virtual epoch. ID allocation does not advance
-time: IDs use a sequence within the current millisecond and explicit IDs are reserved
-against collisions. Exhausting the sequence fails instead of silently moving UTC.
+Snowflake IDs and UTC start from the configured origin (the fixed default is unchanged).
+ID allocation does not advance time: IDs use a sequence within the current millisecond
+and explicit IDs are reserved against collisions. Exhausting the sequence fails instead
+of silently moving UTC.
 Shard-pinned guild fixtures can use an earlier timestamp so they route to the requested
 shard without time travel. Their `created_at` can precede arrangement time, and fixture
 creation order need not match numeric ID order. Normal snowflake timestamps have
 millisecond precision, while backend UTC retains microseconds.
+At the Discord epoch, allocation skips ID zero. A shard request requiring a timestamp
+before that epoch raises `SetupError` without reserving IDs. Allocation beyond the
+64-bit snowflake timestamp range also rejects rather than generating an invalid ID.
 Settlement joins runnable work before and after each timer step. Deadline timers behind
 recognized waits — `wait_for` timeouts on listener waits, View/Modal expiry, `ext.tasks`
 loop intervals and wake-up timers scheduled inside `env.external_wait` — never fire on the
@@ -124,6 +172,14 @@ recognized only when its live loop timer resolves the awaited future; unrelated
 timers do not make an unknown wait look parked. `advance_time()` is itself exclusive with
 other public operations and rejects invalid or negative durations.
 
+Unrecognized waits can have real-due timers handled by the automatic coordinator. That
+fallback advances through its due horizon even when an unrelated input remains blocked,
+still processing resource deadlines before tied bot timers. It does not declare the
+blocked input settled, relax executor ownership or suppress settlement failures.
+Recognized intervals such as typing refresh sleeps remain virtual-only. Explicit
+`advance_time()` still uses strict settlement and reports committed partial progress on
+failure.
+
 If an advance times out, earlier transitions remain committed. The exception notes
 report requested and reached UTC instants. Resolve the outstanding work and advance
 only the remaining duration; do not repeat the original duration or replay an action.