Fix #47: state that only hardware-backed entropy is genuinely random

CLAUDE.md

@@ -53,6 +53,7 @@ Quantum (Facade)
 - **PythonBridge** only passes non-null env vars to preserve boto3 credential chain (IAM Roles).
 - **QPU safety:** Drivers with `synchronous_safe: false` throw on `->run()` to prevent HTTP timeouts.
 - **EntropyGenerator::integer()** uses rejection sampling on a 256-bit batch buffer — never modulo.
+- **Entropy strength is the device's:** only a QPU yields genuinely random bits; the local and managed simulators are pseudorandom. Docblocks and README must never call simulator entropy cryptographically strong.
 
 ## Config
 

README.md

@@ -2,7 +2,7 @@
 
 Laravel package for quantum computing via AWS Braket and local simulators.
 
-Build quantum circuits, generate hardware-grade entropy, and swap backends with a single config change — all with a fluent, Laravel-native API.
+Build quantum circuits, generate entropy from quantum measurements, and swap backends with a single config change — all with a fluent, Laravel-native API.
 
 ## Requirements
 
@@ -109,6 +109,8 @@ $hex = $entropy->hex(128);           // 32-char hex string
 $roll = $entropy->integer(1, 6);     // unbiased die roll (rejection sampling)
 ```
 
+> **Where the randomness comes from.** The bits are the measurement outcomes of qubits placed in superposition, so their quality is the device's. Only a real QPU measures genuinely random bits; the `local` simulator and the managed Braket simulators such as SV1 simulate the circuit classically, and their outcomes come from a pseudorandom number generator. Entropy generation is synchronous, and synchronous runs against a QPU are refused by the synchronous-safety rules, so as shipped `EntropyGenerator` can only reach simulators: treat everything it returns as pseudorandom, fine for development and statistical use, not for keys, tokens or nonces. Use your platform's CSPRNG (`random_bytes()`) for secrets until an asynchronous entropy path exists.
+
 ### Batch Execution
 
 Run several circuits in a single Python process instead of paying the interpreter start-up cost once per circuit. The results come back as a `BatchResult`, ordered like the input, which is arrayable, jsonable, countable and iterable over the individual `CircuitResult` objects.

bin/python/entropy.py

@@ -5,9 +5,11 @@
 runs it with configurable shot count, and writes the resulting random bitstring
 to stdout.
 
-The randomness is quantum in origin: each qubit is placed in an equal
-superposition by a Hadamard gate and then measured, producing truly random bits
-per qubit (on real hardware) or pseudorandom bits (on the local simulator).
+Each qubit is placed in an equal superposition by a Hadamard gate and then
+measured. On real hardware the randomness is quantum in origin and the bits
+are truly random; on any simulator (the local one as well as the managed
+Braket simulators such as SV1) the circuit is simulated classically and the
+bits are pseudorandom.
 Multi-shot support allows generating longer bitstrings efficiently by running
 the circuit multiple times and concatenating all measurement results.
 

config/aether.php

@@ -100,7 +100,7 @@
     |
     | Here you may configure each quantum computing driver. The "local"
     | driver uses the Braket local simulator (no AWS costs). The "aws"
-    | driver connects to AWS Braket for real quantum hardware.
+    | driver connects to AWS Braket for QPUs and managed simulators (the default device_arn is the SV1 simulator).
     |
     | Any driver may declare an optional "python_provider" key pointing at a
     | Python provider module — either a filesystem path to a ".py" file or

src/Contracts/QuantumDevice.php

@@ -18,7 +18,14 @@ interface QuantumDevice
     public function executeCircuit(CircuitBuilder $circuit): CircuitResult;
 
     /**
-     * Generate a cryptographically strong random bit-string of the requested length.
+     * Generate random bytes covering the requested bit count.
+     *
+     * The strength of the randomness is whatever the implementing backend
+     * measures, not a guarantee of this contract: real quantum hardware
+     * yields genuinely random bits, a simulated backend yields pseudorandom
+     * ones. Implementations must not present simulated bits as hardware
+     * entropy, and callers must rely only on hardware-backed implementations
+     * for keys, tokens and nonces.
      */
     public function generateEntropy(int $bits): string;
 }

src/Entropy/EntropyGenerator.php

@@ -9,6 +9,11 @@
 
 /**
  * High-level entropy generator backed by a quantum device.
+ *
+ * The quality of the output is the device's: a QPU measures genuinely
+ * random bits, a simulator (local or managed) draws them from a classical
+ * pseudorandom number generator. Only hardware-backed entropy is suitable
+ * for security-sensitive material such as keys, tokens and nonces.
  */
 class EntropyGenerator
 {