From 019e3afe9766900d99d644d7d4081b2ff14f8795 Mon Sep 17 00:00:00 2001
From: rain <rain@rain.local>
Date: Sun, 14 Jun 2026 08:11:24 -0400
Subject: [PATCH 1/2] docs: document reducer context random APIs

---
 .../00300-reducers/00400-reducer-context.md   | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/docs/00200-core-concepts/00200-functions/00300-reducers/00400-reducer-context.md b/docs/docs/00200-core-concepts/00200-functions/00300-reducers/00400-reducer-context.md
index ac5374516e5..a6fb67f68ba 100644
--- a/docs/docs/00200-core-concepts/00200-functions/00300-reducers/00400-reducer-context.md
+++ b/docs/docs/00200-core-concepts/00200-functions/00300-reducers/00400-reducer-context.md
@@ -272,6 +272,46 @@ The context provides access to a random number generator that is deterministic a
 Never use external random number generators (like `Random` in C# without using the context). These are non-deterministic and will cause different nodes to produce different results, breaking consensus.
 :::
 
+Use the context-provided random API for any reducer logic that needs random values:
+
+<Tabs groupId="server-language" queryString>
+<TabItem value="typescript" label="TypeScript">
+
+```typescript
+const fraction = ctx.random();                         // [0.0, 1.0)
+const roll = ctx.random.integerInRange(1, 6);          // inclusive
+const bytes = ctx.random.fill(new Uint8Array(16));
+```
+
+</TabItem>
+<TabItem value="csharp" label="C#">
+
+```csharp
+double fraction = ctx.Rng.NextDouble();  // [0.0, 1.0)
+int roll = ctx.Rng.Next(1, 7);           // [1, 7)
+```
+
+</TabItem>
+<TabItem value="rust" label="Rust">
+
+```rust
+use spacetimedb::rand::Rng;
+
+let value: u32 = ctx.random();
+let roll: u32 = ctx.rng().gen_range(1..=6);
+```
+
+</TabItem>
+<TabItem value="cpp" label="C++">
+
+```cpp
+auto& rng = ctx.rng();
+int32_t roll = rng.gen_range(1, 6);  // inclusive
+```
+
+</TabItem>
+</Tabs>
+
 ## Module Identity
 
 The context provides access to the module's own identity, which is useful when a reducer needs to refer to the database itself.

From 7f870e00132bbd3caf61bdc68145e03c7020b91f Mon Sep 17 00:00:00 2001
From: rain <rain@rain.local>
Date: Thu, 18 Jun 2026 08:36:05 -0400
Subject: [PATCH 2/2] docs: align reducer skill determinism guidance

---
 skills/concepts/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/concepts/SKILL.md b/skills/concepts/SKILL.md
index 402a1a8ff18..9c4195fc1bd 100644
--- a/skills/concepts/SKILL.md
+++ b/skills/concepts/SKILL.md
@@ -20,7 +20,7 @@ SpacetimeDB is a relational database that is also a server. It lets you upload a
 ## Critical Rules
 
 1. **Reducers are transactional.** They do not return data to callers. Use subscriptions to read data.
-2. **Reducers must be deterministic.** No filesystem, network, timers, or random. All state must come from tables.
+2. **Reducers must be deterministic.** Do not use filesystem, network, external clocks, or external random sources in reducers. Use `ReducerContext` for SpacetimeDB-provided timestamp and deterministic random values.
 3. **Read data via tables/subscriptions**, not reducer return values. Clients get data through subscribed queries.
 4. **Auto-increment IDs are not sequential.** Gaps are normal, do not use for ordering. Use timestamps or explicit sequence columns.
 5. **`ctx.sender` is the authenticated principal.** Never trust identity passed as arguments.