simcord 3.2.2__tar.gz → 3.3.0__tar.gz

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

@@ -4,6 +4,22 @@ This changelog is generated with [towncrier](https://towncrier.readthedocs.io/).
 
 <!-- towncrier release notes start -->
 
+## 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-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simcord
-Version: 3.2.2
+Version: 3.3.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/

{simcord-3.2.2 → simcord-3.3.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

{simcord-3.2.2 → simcord-3.3.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-3.3.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-3.3.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-3.3.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-3.3.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.

{simcord-3.2.2 → simcord-3.3.0}/docs/stability.md

@@ -67,7 +67,7 @@ The public surface is exactly what `simcord` exports from its top-level package
 - the world builders — `GuildHandle`, `ChannelHandle`, `UserHandle`,
   `RoleHandle` — and the `MemberActor` that drives simulated users;
 - `SKUHandle`, `EntitlementHandle`, the Env SKU/entitlement fixture methods,
-  `Env.now()` and `Env.time_context()`;
+  `Env.now()`, `Env.time_context()` and the `Env`/`run` `start_time` option;
 - the result objects `ResponseMessage` and `InteractionResult`;
 - `Preview`, `PreviewCapture`, and the documented `window.simcordPreview` readiness fields for
   the optional local component preview;
@@ -110,6 +110,12 @@ use virtual time without replacing application/global datetime. See
 [simulator policies](guides/monetization.md#evidence-and-open-parity-checks), not captured
 Discord parity; future calibration may correct these policies.
 
+`start_time=None` preserves the 2026-01-01 UTC origin and default generated IDs.
+An aware custom origin takes effect before fixtures/startup and persists across restarts;
+offsets normalize to UTC and unsupported origins fail with `SetupError` before backend
+allocation or runtime hook installation. It does not virtualize application or SQL wall
+clocks. The private `Clock` implementation is not a public clock-provider API.
+
 
 ## What is intentionally internal
 

{simcord-3.2.2 → simcord-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "simcord"
-version = "3.2.2"
+version = "3.3.0"
 description = "Offline discord.py bot testing with pytest. No network, token, or test server."
 readme = "README.md"
 license = "MIT"

simcord-3.3.0/src/simcord/_clock.py

@@ -0,0 +1,35 @@
+"""A backend-owned clock, independent of event loops and environments."""
+
+from datetime import UTC, datetime, timedelta
+
+_DISCORD_EPOCH = datetime(2015, 1, 1, tzinfo=UTC)
+_END_START = _DISCORD_EPOCH + timedelta(milliseconds=1 << 42)
+
+
+class Clock:
+    def __init__(self, start_time: datetime | None = None) -> None:
+        from .backend.errors import SetupError
+
+        if start_time is None:
+            start_time = datetime(2026, 1, 1, tzinfo=UTC)
+        if not isinstance(start_time, datetime):
+            raise SetupError("start_time must be an aware datetime")
+        try:
+            if start_time.utcoffset() is None:
+                raise SetupError("start_time must be an aware datetime")
+            start_time = start_time.astimezone(UTC)
+        except (OverflowError, ValueError, TypeError) as exc:
+            raise SetupError("start_time must normalize to a supported UTC datetime") from exc
+        if not _DISCORD_EPOCH <= start_time < _END_START:
+            raise SetupError(
+                "start_time must be at least 2015-01-01T00:00:00+00:00 "
+                "and before 2154-05-15T07:35:11.104+00:00"
+            )
+        self.elapsed = 0.0
+        self._epoch = start_time
+
+    def now(self) -> datetime:
+        return self._epoch + timedelta(seconds=self.elapsed)
+
+    def advance(self, seconds: float) -> None:
+        self.elapsed += seconds

{simcord-3.2.2 → simcord-3.3.0}/src/simcord/_dpy_internals.py

@@ -17,6 +17,7 @@ from types import ModuleType
 from typing import Any
 
 import discord
+from discord.context_managers import Typing
 from discord.ext import tasks as _ext_tasks
 from discord.gateway import DiscordWebSocket
 from discord.http import HTTPClient
@@ -84,6 +85,7 @@ def verify() -> None:
         (_view.BaseView, "_BaseView__timeout_task_impl"),
         (_ext_tasks.Loop, "_loop"),
         (_ext_tasks.SleepHandle, "_wrapped_set_result"),
+        (Typing, "do_typing"),
         (asyncio.timeouts.Timeout, "_on_timeout"),
     ):
         if not hasattr(cls, attr):  # pragma: no cover - fires only if discord.py drops an internal
@@ -132,6 +134,11 @@ def verify() -> None:
         or "self" not in impl_probe.__code__.co_varnames
     ):  # pragma: no cover
         problems.append("BaseView._BaseView__timeout_task_impl coroutine")
+    typing_impl = getattr(Typing, "do_typing", None)
+    if (
+        not inspect.iscoroutinefunction(typing_impl) or "self" not in typing_impl.__code__.co_varnames
+    ):  # pragma: no cover
+        problems.append("Typing.do_typing coroutine")
     if not hasattr(asyncio.timeouts.Timeout(0.0), "_task"):  # pragma: no cover
         problems.append("Timeout._task")
 
@@ -311,20 +318,50 @@ def tasks_loop_sleep(task: asyncio.Task[Any], waiter: Any) -> bool:
     return getattr(handle, "future", None) is waiter
 
 
+def typing_interval(task: asyncio.Task[Any], waiter: Any) -> bool:
+    """Recognize only the SDK task's direct sleep, including timer construction."""
+    if not isinstance(waiter, asyncio.Future) or waiter.done():
+        return False
+    coro = task.get_coro()
+    if getattr(coro, "cr_code", None) is not Typing.do_typing.__code__:
+        return False
+    frame = getattr(coro, "cr_frame", None)
+    owner = frame.f_locals.get("self") if frame is not None else None
+    if not isinstance(owner, Typing) or getattr(owner, "task", None) is not task:
+        return False
+    sleep = getattr(coro, "cr_await", None)
+    sleep_frame = getattr(sleep, "cr_frame", None)
+    if getattr(sleep, "cr_code", None) is asyncio.sleep.__code__:
+        return sleep_frame is not None and sleep_frame.f_locals.get("future") is waiter
+    # During call_later the coroutine is executing, not yet suspended.
+    # Inspect the exact direct caller, never an HTTP retry's nested sleep.
+    if task is not asyncio.current_task():
+        return False
+    current = inspect.currentframe()
+    try:
+        while current is not None:
+            if current.f_code is asyncio.sleep.__code__:
+                return current.f_locals.get("future") is waiter and current.f_back is frame
+            current = current.f_back
+        return False
+    finally:
+        del current
+
+
 def is_intentional_wait_wakeup(
     client: discord.Client, callback: Any, args: tuple[Any, ...], task: asyncio.Task[Any]
 ) -> bool:
     """True when a timer scheduled right now exists only to resume a wait on this task.
 
     Covers the shapes identifiable at schedule time, before the task suspends:
-    a registered View/Modal expiry task's sleep, an ext.tasks iteration
-    ``SleepHandle``, and a 3.11 ``wait_for`` listener's ``_release_waiter``.
+    a registered View/Modal expiry task's sleep, a native typing interval,
+    an ext.tasks ``SleepHandle``, and a 3.11 listener's ``_release_waiter``.
     Timer wake-ups not identifiable here are still caught at settle time and
     gated at fire time by the env.
     """
     name = getattr(callback, "__name__", "")
     if name == "_set_result_unless_cancelled":
-        return _view_timeout_task_identity(client, task)
+        return _view_timeout_task_identity(client, task) or (bool(args) and typing_interval(task, args[0]))
     if name == "_wrapped_set_result":
         return is_tasks_loop_task(task)
     return name == "_release_waiter" and any(is_listener_future(client, arg) for arg in args)

{simcord-3.2.2 → simcord-3.3.0}/src/simcord/_settlement.py

@@ -153,6 +153,11 @@ def _recognized_wait(self: _SettlementState, task: asyncio.Task[Any], waiter: An
         or (waiter in self.views and not waiter.done())
         or _dpy_internals.view_expiry_task(self.bot, task, waiter, self.expiry_tasks)
         or _dpy_internals.tasks_loop_sleep(task, waiter)
+        or (
+            (record := self.work.tasks.get(task)) is not None
+            and record.generation == self.generation
+            and _dpy_internals.typing_interval(task, waiter)
+        )
     )
 
 
@@ -261,6 +266,14 @@ def _compute_park_reason(self: _SettlementState, task: asyncio.Task[Any], deadli
         return "discord View/Modal expiry timer"
     if _dpy_internals.tasks_loop_sleep(task, waiter) and _timer_records_waking(self, task, waiter):
         return "discord.ext.tasks loop interval"
+    record = self.work.tasks.get(task)
+    if (
+        record is not None
+        and record.generation == self.generation
+        and _dpy_internals.typing_interval(task, waiter)
+        and _timer_records_waking(self, task, waiter)
+    ):
+        return "discord typing interval"
     dependencies = _dpy_internals.composed_tasks(task, waiter)
     unresolved = [dependency for dependency in dependencies if not dependency.done()]
     if unresolved:

{simcord-3.2.2 → simcord-3.3.0}/src/simcord/actors.py

@@ -67,6 +67,8 @@ class MemberActor:
         return cached.get_member(self.id) if cached else None
 
     def _check(self, channel: ChannelHandle, *permissions: str) -> None:
+        _require_handle(self._env, channel)
+        _check_user_dm_channel(self, channel.id)
         _require_handle(self._env, channel, guild_id=self.guild.id)
         self._env.backend.require_permissions(self.guild.id, self.id, channel.id, *permissions)
 
@@ -626,18 +628,29 @@ _ENTITY_SELECT_HANDLES: dict[ComponentType, tuple[type, ...]] = {
 
 def _check_actor_channel(actor: Any, channel: ChannelHandle) -> None:
     guild = getattr(actor, "guild", None)
-    _require_handle(actor._env, channel, guild_id=guild.id if guild is not None else None)
+    _require_handle(actor._env, channel)
     _check_user_dm_channel(actor, channel.id)
+    _require_handle(actor._env, channel, guild_id=guild.id if guild is not None else None)
     if not can_access_channel(actor._env, channel.id, actor):
         raise SetupError("That channel is not accessible to this user")
 
 
 def _check_user_dm_channel(actor: Any, channel_id: int) -> None:
-    if isinstance(actor, UserHandle) and actor._env.backend.dm_channels.get(actor.id) != channel_id:
+    if isinstance(actor, MemberActor) and actor._env.backend.dm_channels.get(actor.id) == channel_id:
         raise SetupError(
-            "UserHandle interaction operations are restricted to this user's DM channel — "
-            "a real user could not interact with guild messages"
+            "MemberActor is scoped to its guild, not this user's bot DM — "
+            "use member.user.send_dm(...) for messages or member.user for "
+            "slash, autocomplete, click, select, and submit_modal. "
+            "member.send_dm(...) remains supported"
         )
+    if isinstance(actor, UserHandle) and actor._env.backend.dm_channels.get(actor.id) != channel_id:
+        channel = actor._env.backend.channels.get(channel_id)
+        if channel is not None and channel.guild_id is not None:
+            raise SetupError(
+                "UserHandle operations are DM-scoped — use a MemberActor belonging to "
+                "the target guild for guild messages and interactions"
+            )
+        raise SetupError("UserHandle operations are restricted to this user's DM channel")
 
 
 def _visible_message(actor: Any, message: MessageLike) -> Any:

{simcord-3.2.2 → simcord-3.3.0}/src/simcord/backend/ops/base.py

@@ -40,7 +40,8 @@ from ..models import (
 )
 
 # Snowflakes embed milliseconds since Discord's epoch; allocation never moves UTC.
-_DISCORD_EPOCH_MS = 1420070400000
+_DISCORD_EPOCH = datetime.datetime(2015, 1, 1, tzinfo=datetime.UTC)
+_MILLISECOND = datetime.timedelta(milliseconds=1)
 
 EventListener = Callable[[str, Mapping[str, Any]], None]
 
@@ -106,7 +107,9 @@ class BackendBase:
         return value
 
     def _allocate_at(self, milliseconds: int) -> int:
-        sequence = self._sequences.get(milliseconds, 0)
+        if not 0 <= milliseconds < 1 << 42:
+            raise errors.SetupError("generated snowflake timestamp is outside the 64-bit range")
+        sequence = self._sequences.get(milliseconds, 1 if milliseconds == 0 else 0)
         while sequence < 1 << 22:
             value = (milliseconds << 22) | sequence
             sequence += 1
@@ -118,12 +121,12 @@ class BackendBase:
 
     def snowflake(self) -> int:
         """Allocate at current UTC, using all 22 low bits without advancing time."""
-        milliseconds = int(self.clock.now().timestamp() * 1000) - _DISCORD_EPOCH_MS
+        milliseconds = (self.clock.now() - _DISCORD_EPOCH) // _MILLISECOND
         return self._allocate_at(milliseconds)
 
     def snowflake_for_shard(self, shard_id: int, shard_count: int) -> int:
         """Allocate at the latest historical millisecond belonging to this shard."""
-        milliseconds = int(self.clock.now().timestamp() * 1000) - _DISCORD_EPOCH_MS
+        milliseconds = (self.clock.now() - _DISCORD_EPOCH) // _MILLISECOND
         milliseconds -= (milliseconds - shard_id) % shard_count
         return self._allocate_at(milliseconds)