simcord 3.0.2__tar.gz → 3.2.0__tar.gz

{simcord-3.0.2 → simcord-3.2.0}/CHANGELOG.md

@@ -4,13 +4,65 @@ This changelog is generated with [towncrier](https://towncrier.readthedocs.io/).
 
 <!-- towncrier release notes start -->
 
+## 3.2.0 (2026-10-22)
+
+### Features
+
+- Add offline SKU and entitlement simulation: catalog/history/live fixtures, six REST routes, interaction access, gateway lifecycle, consumable fulfilment, replay and restart reconciliation. Publish explicit uncalibrated Discord edge policies and the observations needed to reach parity. Unify virtual UTC with chronological resource/timer advancement and supported SDK clock helpers; allocating IDs no longer moves time. Enforce one live Env per loop and preserve application entitlements when the bot leaves a guild.
+
+  Retain undelivered automatic-clock settlement failures until a public operation receives them, and select pytest virtual UTC from the unique running environment even when fixtures also expose inactive foreign worlds.
+
+  Add an opt-in user-subscription reference recorder with hidden token entry, raw protocol evidence, authorized interaction checkpoints, session-owned test-grant cleanup and a local boundary self-check.
+
+  Correct reference-recorder subscription scope detection using named SDK flags; accept unpublished user SKUs and reject guild-only or ambiguous matches.
+
+  Fix stalled reference interaction checkpoints by decoding discord.py's supported raw Gateway receive event; exercise probe advancement through a local WebSocket and SDK dispatch in the self-check.
+
+  Preserve rejected different-SKU and post-deletion recreation probes as reference evidence without aborting the remaining subscription capture sequence.
+
+  Add a manual Application Test Mode purchase capture mode for consumable/repeated consumption and durable wrong-kind consumption. Require operator test-mode confirmation and new type-4 app/SKU/user-matched entitlements before consumption; retain purchase IDs and leave preexisting/live entitlements untouched.
+
+  Prepare remaining reference evidence with a paced rejection/duplicate/pagination runner, optional guild and legitimate lifecycle capture, durable ownership journals and safe recovery. Add a raw-evidence validator for new and existing bundles; report unavailable prerequisites without claiming full parity or repeating purchase flows.
+
+  Extend the follow-up recorder with unpublished same-app guild SKU selection, two-server/two-member projection checks, cross-scope grant ordering and owner validation. Add explicit fresh deleted-unconsumed purchase capture and optional zero-total team live-upgrade capture, with per-server command provenance, raw-evidence validation, resumable manual purchase IDs and persistent real-subscription cancellation obligations.
+
+  Fix checkout baselines stopping on 100 retained test grants by traversing complete history and validating both cursor branches. Resume blocked checkout stages without replaying completed guild/purchase sections, correlate interaction checkpoints to their accepted invocation, print blocker reasons and numbered checkout steps, and retain deleted-unconsumed evidence without a stale missing-fixture blocker.
+
+  Recognize observed PURCHASE-type live subscription entitlements alongside APPLICATION_SUBSCRIPTION for selection and cancellation recovery, retaining exact app/SKU/user and type-4 mutation boundaries. Preserve cancellation-only recovery after failed checkout identification and validate cleaned historical commands across recorder resumes.
+
+  Use complete subscription-list objects as authoritative cancellation proof instead of discarding them when a redundant detail lookup fails. Clear stale blocker reasons after positive verification and retain exact-reference, audited offline recovery without repeating Discord actions or altering raw protocol streams.
+
+  Add an expiry-only follow-up that derives and hashes an authenticated canceled-subscription source, reuses its before interaction, revalidates the real billing schedule, captures entitlement/subscription events and polls, and needs one post-end command. Automate a provenance-safe post-end sandbox grant probe/cleanup, preserve late-start and unavailable-reporting limits, and resume without repeating successful interactions or known grant outcomes.
+
+  Add an immediate upgrade/scheduled-downgrade follow-up linked to existing canceled-A evidence. Reuse, resume or freely restart A, capture A→B and cross-tier sandbox overlap, record pending B→A renewal, and verify cancellation for every managed real entitlement. Preserve missing-probe-only recovery, bounded read-only propagation settling and raw downgrade evidence links; reject manual/wrong-type/SKU/owner create receipts before cleanup ownership.
+
+  Calibrate monetization against bounded Discord reference captures without claiming full parity. Migrate catalog fixtures to explicit subscription groups and matching scope flags; interaction entitlements are stably guild-first, while REST pagination descends for default/before and ascends for after. API test grants retain null dates and guild bot purchasers, cross-tier scoped subscription conflicts, structured owner-validation errors and corrected Invalid SKU/Unknown SKU statuses. Consume/delete now reject repeats or deleted rows with calibrated errors; type-4 purchases permit DELETE without implying recorder cleanup ownership. Correct consumed-field presence and fulfillment/source metadata, preserving observed upgrade UPDATE snapshots separately from committed REST state. Document discord.py 2.7.1 raw-history traversal and distinguish fixture policy, unsupported billing/reporting and unverified lifecycle boundaries.
+
+  Harden recorder credential redaction and verify test-create receipts before granting cleanup ownership. Require explicit unconsumed state for consumables while preserving omitted consumed fields on durable purchases.
+
+### Miscellaneous
+
+- Require certifi>=2026.10.19 for documentation dependencies and update the lock, removing the affected eMudhra root certificate from its CA bundle. Existing environments require a separate dependency sync.
+
+
+## 3.1.0 (2026-10-16)
+
+### Features
+
+- Thinking interaction defers now create fetchable, stable-ID originals; completing them through the first followup preserves defer-time visibility, while later followups are independent. Initial callbacks expire after three seconds (`10062`), separately from 15-minute continuation tokens (`10015`) and deleted originals (`10008`).
+
+  Add native actor and SDK forwarding with immutable rich snapshots, shared Message Content projection, permissions, and frozen Preview media authorized against the forward rather than the live source. Reject foreign-environment message handles before deterministic-ID resolution. Already-forwarded sources remain explicitly unsupported; snapshot metadata is copied while immutable CDN bytes are reused.
+
+  Keep strict task-scoped settlement diagnostics, but withdraw the unsafe blanket framework-run adapter recipe: only verified external handoffs should be declared, and no generic pydantic-ai adapter is established.
+
+
 ## 3.0.2 (2026-10-16)
 
 ### Bug fixes
 
 - Honor explicit application Message Content approval on REST message responses independently of Gateway intents, including nested references. Restore ping-enabled replies to regular bot messages without exposing replies to interaction responses, preserve contextual interaction/token access, and keep backend fixtures complete. The default `approved_intents=None` retains unrestricted REST access; explicit absent approval is restricted.
 
-  Explicitly unapproved applications now receive redacted REST content, so tests that previously relied on unauthorized reads may fail and expose consumer bugs. Selecting a message in an interaction does not authorize later REST reads. Reply wire metadata and edit/deletion details remain offline-tested rather than live-Discord calibrated. ([#message-content-visibility](https://github.com/SilentHacks/simcord/issues/message-content-visibility))
+  Explicitly unapproved applications now receive redacted REST content, so tests that previously relied on unauthorized reads may fail and expose consumer bugs. Selecting a message in an interaction does not authorize later REST reads. Reply wire metadata and edit/deletion details remain offline-tested rather than live-Discord calibrated.
 
 
 ## 3.0.1 (2026-10-06)

{simcord-3.0.2 → simcord-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simcord
-Version: 3.0.2
+Version: 3.2.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/
@@ -39,6 +39,7 @@ Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.8; extra == 'dev'
 Requires-Dist: towncrier>=24; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: certifi>=2026.10.19; extra == 'docs'
 Requires-Dist: mkdocs-material>=9; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
 Provides-Extra: preview

{simcord-3.0.2 → simcord-3.2.0}/docs/api.md

@@ -24,7 +24,17 @@ top-level `simcord` package unless a module-qualified path is shown.
 `settle_timeout` is the default maximum time spent joining runnable bot work. A direct
 `await env.settle(timeout=...)` override is available; `idle=` is only the polling interval.
 Use `await env.external_wait(awaitable, reason="...")` for one explicitly scoped external
-input wait. Unknown waits remain active and produce a diagnostic timeout.
+input wait. It applies to the calling task only. Unknown waits remain active and produce
+a diagnostic timeout. Do not label whole framework runs as external waits; see the
+[framework integration limits](concepts.md#actors-act-as-a-real-user).
+
+### `Env(approved_intents=None)`
+
+`None` skips explicit privileged-intent approval checks and permits REST Message Content
+access, preserving the permissive fixture default. An explicit `discord.Intents.none()`
+denies that access. REST authorization follows this Portal/API setting independently of
+the bot's requested Gateway mask; normal exemptions and interaction-selected access remain.
+Bot-visible projections never redact authoritative actor/backend fixture state.
 
 
 ## Request observability
@@ -50,6 +60,20 @@ methods. See [Core concepts → Builders](concepts.md#builders-arrange-the-world
 
 ::: simcord.UserHandle
 
+### SKUs and entitlements
+
+`Env.create_sku()` arranges explicit catalog entries (including non-grantable groups);
+`seed_entitlement()` arranges history without CREATE; `await grant_entitlement()` emits
+a live grant and settles. Recover a committed grant by ID with `get_entitlement()`.
+See [SKUs & entitlements](guides/monetization.md) for calibrated REST fields/errors,
+cross-tier sandbox conflicts, guild-first access, raw history traversal and the separate
+fixture policies, unsupported subscription billing/reporting and unverified boundaries.
+
+::: simcord.SKUHandle
+
+::: simcord.EntitlementHandle
+
+
 ## Actors
 
 The simulated human that drives your bot. Created by `guild.add_member(...)`. See

{simcord-3.0.2 → simcord-3.2.0}/docs/concepts.md

@@ -57,11 +57,19 @@ Common builders:
 | `guild.create_text_channel(name, *, overwrites=…, topic=…)` | A `ChannelHandle`. |
 | `guild.create_role(name, *, permissions=…)` | A `RoleHandle`. |
 | `guild.add_member(user, *, roles=…, nick=…)` | A `MemberActor` (the user, now in the guild). |
+| `env.create_sku(name)` | A `SKUHandle`; subscription groups are generated automatically. |
+| `env.seed_entitlement(sku, guild=… / user=…)` | Historical `EntitlementHandle`, without CREATE. |
+| `await env.grant_entitlement(sku, guild=… / user=…)` | Live entitlement, CREATE, and settled bot reactions. |
 
 !!! tip "`env.guild` is a shortcut"
     The first guild you create is available as `env.guild`, for the common single-guild
     test. `env.guild.create_text_channel(...)` reads nicely.
 
+Live entitlement grants are deliberately async: unlike historical seeding, they deliver
+a causal event and settle it. Both handles expose detached real SDK `snapshot()` models.
+The grant may already be committed when settlement times out; recover by ID, do not retry.
+See [SKUs & entitlements](guides/monetization.md) for lifecycle and parity boundaries.
+
 ## Actors — act as a real user
 
 **Actors are async and permission-checked.** A `MemberActor` (returned by
@@ -112,6 +120,22 @@ input:
 await env.external_wait(stop.wait(), reason="wait for the next message")
 ```
 
+Declarations are **task-scoped**, not inherited. A framework can have three distinct waits:
+graph-event delivery in its caller, a lifecycle wrapper waiting for that caller to finish,
+and a model/provider task waiting for external input. Declaring only the provider wait does
+not make the other two safe to ignore. Declare only verified external handoffs through
+the framework's public hooks; do not infer safety from coroutine names or suppress
+every sibling task.
+
+Do **not** wrap an entire `agent.run()` or lifecycle `wrap_run(handler)` in
+`external_wait`. Ordinary initialization and finalization also run there, and timers
+created by the declaring task become virtual. Even an ordinary initialization sleep
+can then stop progressing without `env.advance_time()`. No safe generic pydantic-ai
+framework adapter is established here: declaring a provider/backoff wait alone does
+not solve its orchestration waits. Keep undeclared workers visible as errors rather
+than weakening settlement to make the integration pass.
+
+
 Successful settlement means no runnable tracked bot work remains. Public operations reject
 overlap before mutating state, and teardown cancels only bot-owned work; caller tasks survive.
 
@@ -119,7 +143,7 @@ The actor verbs, by area:
 
 | Area | Verbs |
 | --- | --- |
-| Text | `send`, `edit`, `delete`, `typing`, `send_dm` |
+| Text | `send`, `forward`, `edit`, `delete`, `typing`, `send_dm` |
 | Reactions | `react`, `unreact` |
 | App commands | `slash`, `context_menu`, `autocomplete` |
 | Components | `click`, `select`, `submit_modal` |

{simcord-3.0.2 → simcord-3.2.0}/docs/guides/ai-coding-agents.md

@@ -25,6 +25,7 @@ Copy the following into your project's `AGENTS.md`, `CLAUDE.md`, or equivalent a
 - Exercise behavior through `simcord_env` builders and actors. Do not call a
   command callback directly when the contract depends on discord.py dispatch.
 - Slash, autocomplete, and context-menu actor calls enforce command visibility; inspect `available_commands()` or arrange permissions and contexts in the fixture, and use `UserHandle.slash()` / `.autocomplete()` for bot-DM commands.
+- For premium flows use `create_sku`, `seed_entitlement` for history and async `grant_entitlement` for live CREATE; exercise real SDK consume/reconcile paths. Read the monetization guide's open parity checks before assuming undocumented Discord edge behavior.
 - Keep tests offline. Never request, invent, log, or connect with a Discord token.
 - Assert observable results from SimCord handles or the bot's real discord.py cache.
 - Keep pure business logic in ordinary unit tests and mock only application-owned
@@ -92,6 +93,11 @@ The agent can now implement or repair the command against a stable contract.
 
 This loop works for prefix commands, slash commands, autocomplete, context menus, views, modals, permissions, events, cooldowns, and sharded bots.
 
+For premium access and fulfilment, use [SKUs & entitlements](monetization.md).
+SimCord owns Discord resource simulation, not the bot's plans, allowances, trials or ledger.
+Use `env.now` as an injected application clock and `env.time_context()` for manual-driver
+SDK UTC reads; never replace the application's global datetime module.
+
 ## Prompt for a coding agent
 
 ```text

{simcord-3.0.2 → simcord-3.2.0}/docs/guides/fixtures.md

@@ -67,8 +67,9 @@ asyncio_mode = "auto"
 
 ## Without pytest
 
-Don't use pytest, or want a second environment in one test? Use `simcord.run` directly — an
-async context manager that yields the same `Env`:
+Use `simcord.run` directly for explicit lifecycle control — an async context manager that
+yields the same `Env`. Only one live environment per event loop is supported; shut it
+down before starting another on that loop.
 
 ```python
 import simcord
@@ -108,6 +109,18 @@ migration bridge does not change command registration.
 
 External waits must be scoped with `await env.external_wait(awaitable, reason="...")`; unknown waits time out. Overlapping actor, builder, lifecycle, and time-control operations reject before mutation. Teardown cancels bot-owned work but leaves caller-owned tasks alive.
 
+Supported SDK UTC helpers use the selected Env clock automatically during the actual
+pytest test call (including fixtures aliased under another name) when there is one
+running Env. Direct `async with simcord.run(...)` also selects it. For manual
+`Env.start()` / `shutdown()` use `with env.time_context():` around driver SDK time reads;
+inject `env.now` for your own application clocks. Custom async fixtures should use manual
+start/shutdown rather than retaining a `run` ContextVar token across `yield`, which older
+pytest-asyncio versions can resume in another context.
+
+Before startup, `create_sku` and `seed_entitlement` can arrange the state that
+`setup_hook` reconciles over REST. Live `grant_entitlement` and handle transitions require
+a running Env. See [SKUs & entitlements](monetization.md).
+
 ```python
 # An isolated unit test that doesn't care about sync, and inspects errors itself:
 async with simcord.run(bot, strict_sync=False) as env:

{simcord-3.0.2 → simcord-3.2.0}/docs/guides/intents.md

@@ -108,6 +108,8 @@ the bot's event callbacks or SDK fetches to assert its restricted view. The tran
 also retains authoritative event data and is **not** a privacy-redacted export.
 These contracts are covered offline; reply wire metadata and edit/deletion details
 have not been calibrated against a live Discord capture.
+Forward snapshots inherit their containing message's content access: redaction removes
+content-bearing fields while retaining snapshot metadata.
 
 ## Member chunking
 

{simcord-3.0.2 → simcord-3.2.0}/docs/guides/interactions.md

@@ -43,13 +43,13 @@ everything the bot did in response:
 
 ```python
 result.acknowledged          # did the bot respond at all?
-result.deferred              # responded with "thinking…" (deferred)
+result.deferred              # an original is still loading, or a component update was deferred
 result.ephemeral             # the response is only visible to the invoker
 result.response              # the response message (ResponseMessage | None)
 result.response.content      # its text
 result.response.embeds       # list[discord.Embed]
 result.response.message      # the full discord.Message, when you need it
-result.followups             # messages sent via interaction.followup
+result.followups             # independent followup messages, excluding completion of a thinking original
 result.modal                 # the modal payload, if one was shown
 result.autocomplete_choices  # choices, for autocomplete interactions
 ```
@@ -83,23 +83,54 @@ matching error-acknowledgement transition.
 
 The full lifecycle behaves as on Discord:
 
-- **Deferring** — `await interaction.response.defer()` sets `result.deferred`; a later
-  `edit_original_response` / `followup.send` materialises the message.
+- **Initial deadline** — reply or defer before three seconds on the backend clock.
+  An unacknowledged callback at or after that deadline fails with `10062` (Unknown
+  Interaction), and its continuation token is invalid. Use `env.advance_time()` to
+  exercise this boundary without wall-clock sleeps.
+
+- **Thinking defers (type 5)** — `await interaction.response.defer(thinking=True)` immediately
+  creates a fetchable original with `flags.loading`, its chosen ephemeral flag, and a stable
+  message ID. Public originals appear in public history; private ones are visible only to
+  the invoker.
+- **Completing a thinking defer** — `edit_original_response()` is the preferred endpoint.
+  Discord's deprecated compatibility behavior also lets the first `followup.send()` complete
+  that same original. Both clear loading without changing its ID or visibility; a conflicting
+  `ephemeral=` flag cannot turn an existing public message private (or vice versa).
+- **Component update defers (type 6)** — `defer()` without `thinking=True` keeps the clicked
+  message as the original. A followup is independent and does not consume or replace it.
 - **Double-acknowledging** — responding twice raises the real Discord error `40060`. (A
   callback that *fails* — e.g. a 400 from an oversized embed — does **not** consume the
   interaction, so a retried response still gets through.)
-- **Followups** — messages sent via `interaction.followup` land in `result.followups`.
-- **`@original` operations** — editing, fetching and deleting the original response resolve
-  to the right message, including for deferred component interactions.
+- **Followups** — after the original is completed, `interaction.followup.send()` creates an
+  independent message with its requested visibility. Only these messages enter
+  `result.followups`; completion of a thinking original is available as `result.response`.
+- **`@original` operations** — fetching, editing and deleting resolve the same stored message.
+  Deletion returns `result.response` to `None`, and later original reads/edits fail with
+  `10008`; a deleted pending original cannot be resurrected by a followup. Deleting an
+  already-completed original does not prevent independent followups.
+- **Token expiry** — continuation webhooks expire after 15 minutes on the backend clock.
+  Expired tokens fail with `10015`, distinct from an absent/deleted message's `10008`.
 
 ```python
 async def test_defer_then_followup(simcord_env):
     ...
     result = await alice.slash(channel, "slow-task")
-    assert result.deferred
-    assert result.followups[0].content == "Done!"
+    assert not result.deferred
+    assert result.response.content == "Done!"
+    assert result.followups == []
 ```
 
+This corrects the former first-followup-as-new-message behavior: migrate assertions from
+`result.followups[0]` to `result.response` when the send completes a thinking original.
+Pending originals also consume a message ID immediately, rather than on completion.
+
+discord.py caches `interaction.original_response()` as a snapshot. To observe a later edit,
+fetch fresh state with `interaction.followup.fetch_message(original.id)`; SimCord does not
+patch the SDK cache. Choose private visibility at the initial defer when a response may
+contain sensitive data. If visibility must change, complete the original without sensitive
+content before sending a new, independently visible followup.
+
+
 ## Autocomplete
 
 Type into an autocomplete option and get back the choices the bot offered:

{simcord-3.0.2 → simcord-3.2.0}/docs/guides/messages.md

@@ -47,6 +47,42 @@ Editing a message preserves immutable flags: ephemeral messages stay ephemeral,
     on. If your test setup denies the action, you get a `SetupError` — see
     [Permissions](permissions.md).
 
+## Forwarding immutable message snapshots
+
+```python
+source = await alice.send(channel, "Evidence", attachments=[("proof.txt", b"original")])
+forwarded = await alice.forward(source, destination)
+assert forwarded.reference.type is discord.MessageReferenceType.forward
+assert forwarded.message_snapshots[0].content == "Evidence"
+assert await forwarded.message_snapshots[0].attachments[0].read() == b"original"
+```
+
+Bot code can use native `await message.forward(destination)` too. Both paths store a
+type-1 reference and a snapshot, rather than a reply's live `referenced_message`. Forwarding
+does not ping the original author. Source visibility/history and destination send/attachment
+permissions are enforced; SDK forwarding also requires application-level content access.
+Actor message handles must belong to the same environment; colliding deterministic
+IDs from another environment do not identify a local source. Cross-guild forwarding
+within one environment remains supported, including SDK interaction originals and
+webhook followups. Message handles retained across a bot restart remain environment-owned.
+
+Snapshot metadata is copied when the forward is created and detached on observation. Later
+source edits/deletion and mutations of returned objects do not alter it. Existing immutable
+CDN bytes are reused, not duplicated. Actors and fixture history see authoritative snapshots;
+bot Gateway/REST observations apply the normal Message Content policy.
+
+Preview renders the frozen text, embeds, attachments, stickers and components without
+inventing a source author or resolving a live reply. Historical interaction controls are
+disabled; safe link buttons remain links. Snapshot downloads are authorized against the
+forwarding message, not the source: readers of a deliberately shared forward need not have
+source-channel access, but deleting the forward revokes its retained downloads.
+
+**Explicit limit:** forwarding an already-forwarded message raises `NotImplementedError`.
+Discord documents a nesting cap but not the transformation of nested snapshots plus outer
+annotations; SimCord does not silently flatten/drop content or fabricate a Discord error.
+Ordinary forwards, including outer annotations sent through the native SDK, are supported.
+
+
 ## Converters and checks run for real
 
 Because the cache is populated through discord.py's actual parsers, converters resolve