qr_reader-native 0.0.1

data/ext/qr_reader_native/sp_process_status.c

@@ -0,0 +1,211 @@
+/* sp_process_status.c -- Process::Status runtime.
+ *
+ * The runtime is deliberately tiny: a heap-allocated struct holding
+ * pid + raw status, plus the W*() bit-field accessors from
+ * <sys/wait.h> wrapped as sp_int-returning helpers. Spinel's
+ * boxing layer (sp_box_obj) carries the type tag (cls_id =
+ * SP_BUILTIN_PROCESS_STATUS) so the codegen can dispatch
+ * `result[1].signaled?` to the right accessor at the call site.
+ *
+ * This TU is compiled into libspinel_rt.a; it does NOT need
+ * spinel_rt.h. It does include sp_alloc.h for sp_gc_alloc.
+ */
+#include <stddef.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+#include <sys/wait.h>
+
+#include "sp_alloc.h"   /* sp_RbVal, sp_gc_alloc, sp_raise_cls */
+#include "sp_process_status.h"
+
+/* The W*() macros must be handed an int LVALUE, not a cast expression. macOS
+   still defines them through the legacy `union wait` bridge --
+   `#define _W_INT(w) (*(int *)&(w))` -- so the macro takes the ADDRESS of its
+   argument, and `WIFEXITED((int)s)` fails to compile there with "cannot take
+   the address of an rvalue". glibc casts instead of dereferencing, which is
+   why this built on Linux. Each accessor below copies its sp_int argument
+   into `int st` first and passes that. */
+
+/* CRuby answers nil for exitstatus on a signaled status and for termsig on
+   one that exited, and spinel already has a spelling for a nullable Integer:
+   SP_INT_NIL, which every renderer and `.nil?` understands. -1 is a real
+   Integer here -- `p st.termsig` printed -1 rather than nil. */
+#define SP_STATUS_NIL SP_INT_NIL
+
+/* ---- allocator ---- */
+
+sp_ProcessStatus *sp_process_status_recv(sp_ProcessStatus *p, const char *meth) {
+  extern void sp_nil_recv(const char *meth);   /* sp_str.c */
+  if (!p) sp_nil_recv(meth);
+  return p;
+}
+
+sp_ProcessStatus *sp_last_process_status(void) {
+  extern int sp_last_status, sp_last_pid;   /* sp_system.c */
+  if (!sp_last_pid) return NULL;
+  sp_ProcessStatus *p = (sp_ProcessStatus *)sp_gc_alloc(sizeof(sp_ProcessStatus), NULL, NULL);
+  if (!p) sp_raise_cls("NoMemoryError", "out of memory");
+  p->pid = sp_last_pid;
+  p->status = sp_last_status;
+  return p;
+}
+
+sp_ProcessStatus *sp_process_status_new(sp_int pid, sp_int status) {
+  if (status < 0 || status > 0xFFFF) {
+    sp_raise_cls("ArgumentError", "invalid status word");
+  }
+  sp_ProcessStatus *p = (sp_ProcessStatus *)sp_gc_alloc(sizeof(sp_ProcessStatus), NULL, NULL);
+  if (!p) sp_raise_cls("NoMemoryError", "out of memory");
+  p->pid = pid;
+  p->status = status;
+  return p;
+}
+
+/* sp_box_process_status is declared in sp_alloc.h (with a forward
+   struct decl, so sp_alloc.h does not need to include
+   sp_process_status.h). The impl lives here so a TU that links
+   against the runtime (e.g. sp_process.c) does not need to
+   include sp_process_status.h to box a Status. */
+sp_RbVal sp_box_process_status(sp_ProcessStatus *p) {
+  return sp_box_obj(p, SP_BUILTIN_PROCESS_STATUS);
+}
+
+/* ---- predicates ---- */
+
+int sp_process_status_exited_p(sp_int s) {
+  int st = (int)s;
+  return WIFEXITED(st) ? 1 : 0;
+}
+
+int sp_process_status_signaled_p(sp_int s) {
+  int st = (int)s;
+  return WIFSIGNALED(st) ? 1 : 0;
+}
+
+int sp_process_status_coredump_p(sp_int s) {
+  int st = (int)s;
+  if (!WIFSIGNALED(st)) return 0;
+  return WCOREDUMP(st) ? 1 : 0;
+}
+
+/* Tri-state, because CRuby's is: true when the process exited with status 0,
+   false when it exited with anything else, and NIL when it did not exit
+   normally at all. -1 is that nil; the call site boxes it. */
+int sp_process_status_success_p(sp_int s) {
+  int st = (int)s;
+  if (!WIFEXITED(st)) return -1;
+  return WEXITSTATUS(st) == 0 ? 1 : 0;
+}
+
+/* ---- accessors ---- */
+
+sp_int sp_process_status_pid(sp_int s) {
+  /* The runtime only sees the status word (the pid travels alongside
+     in the boxed struct). Returning the lower byte of the status is
+     wrong -- the pid is a separate field. The pid is in the boxed
+     struct, accessible via sp_ProcessStatus*.pid. To keep the
+     signature simple the accessor takes the status word; the pid
+     access is plumbed via a separate sp_process_status_pid_of helper
+     that takes the boxed struct. */
+  /* This path is unused: the codegen path uses
+     sp_process_status_pid_of for the boxed struct. */
+  (void)s;
+  return 0;
+}
+
+sp_int sp_process_status_exitstatus(sp_int s) {
+  int st = (int)s;
+  if (!WIFEXITED(st)) return SP_STATUS_NIL;
+  return (sp_int)WEXITSTATUS(st);
+}
+
+sp_int sp_process_status_termsig(sp_int s) {
+  int st = (int)s;
+  if (!WIFSIGNALED(st)) return SP_STATUS_NIL;
+  return (sp_int)WTERMSIG(st);
+}
+
+/* ---- boxed-struct pid access ---- */
+/* The codegen needs the pid of a boxed Process::Status. The runtime
+   accessor signatures above take the raw status word, so the pid
+   accessor goes through a separate helper that takes the boxed
+   struct directly. */
+
+sp_int sp_process_status_pid_of(sp_ProcessStatus *st) {
+  return st->pid;
+}
+
+/* ---- equality ---- */
+
+int sp_process_status_eq(sp_int a, sp_int b) {
+  return a == b;
+}
+
+/* ---- to_s / inspect ----
+ *
+ * CRuby renders:
+ *   exited normally:    "exit 0"            (or "exited" prefix for inspect)
+ *   signaled:           "signal 9 (SIGKILL)" (or "signaled" prefix for inspect)
+ *   unknown:            ""? (CRuby raises; we return a generic string)
+ *
+ * The output goes into a static buffer; the codegen copies it via
+ * sp_str_dup_external when boxing the result as a String.
+ */
+
+static const char *sp_signal_name(int sig) {
+  /* A short list. CRuby maps every signal; we cover the common ones
+     so dvtm's signal detection reads naturally in log output. */
+  switch (sig) {
+    case  1: return "SIGHUP";
+    case  2: return "SIGINT";
+    case  3: return "SIGQUIT";
+    case  4: return "SIGILL";
+    case  6: return "SIGABRT";
+    case  8: return "SIGFPE";
+    case  9: return "SIGKILL";
+    case 11: return "SIGSEGV";
+    case 13: return "SIGPIPE";
+    case 15: return "SIGTERM";
+    case 24: return "SIGXCPU";
+    default: return NULL;
+  }
+}
+
+static SP_TLS char sp_status_buf[96];
+
+const char *sp_process_status_to_s(sp_int pid, sp_int s, int is_inspect) {
+  /* CRuby's pst_message: "pid N", then how the child ended */
+  const char *prefix = is_inspect ? "#<Process::Status: " : "";
+  const char *suffix = is_inspect ? ">" : "";
+  int st = (int)s;
+  if (WIFEXITED(st)) {
+    snprintf(sp_status_buf, sizeof sp_status_buf,
+             "%spid %lld exit %d%s", prefix, (long long)pid, WEXITSTATUS(st), suffix);
+  }
+  else if (WIFSIGNALED(st)) {
+    int sig = WTERMSIG(st);
+    const char *name = sp_signal_name(sig);
+    const char *core = WCOREDUMP(st) ? " (core dumped)" : "";
+    if (name) {
+      snprintf(sp_status_buf, sizeof sp_status_buf,
+               "%spid %lld %s (signal %d)%s%s", prefix, (long long)pid, name, sig, core, suffix);
+    }
+    else {
+      snprintf(sp_status_buf, sizeof sp_status_buf,
+               "%spid %lld signal %d%s%s", prefix, (long long)pid, sig, core, suffix);
+    }
+  }
+  else {
+    snprintf(sp_status_buf, sizeof sp_status_buf,
+             "%spid %lld status 0x%llx%s", prefix, (long long)pid, (unsigned long long)s, suffix);
+  }
+  return sp_status_buf;
+}
+
+/* A fresh String each call: the rendering's static buffer is shared, and
+   `[$?.to_s, $?.inspect]` read the second rendering twice. */
+const char *sp_process_status_str(sp_ProcessStatus *p, int is_inspect) {
+  if (!p) return sp_str_dup_external(is_inspect ? "nil" : "");
+  return sp_str_dup_external(sp_process_status_to_s(p->pid, p->status, is_inspect));
+}

data/ext/qr_reader_native/sp_process_status.h

@@ -0,0 +1,66 @@
+/* sp_process_status.h -- Process::Status value type.
+ *
+ * Process.waitpid2 returns [pid, status] where status is a
+ * Process::Status instance. This file provides the boxed runtime
+ * type plus the small set of predicates and accessors CRuby
+ * exposes on Process::Status.
+ *
+ * Layout: a single int (the raw waitpid(2) status word) plus the
+ * pid of the child the status is from. Heap-allocated because
+ * the per-instance id-tag is needed for the typecheck on
+ * `result[1].signaled?` and the like; the struct itself is small
+ * (16 bytes) so the allocation is cheap.
+ */
+#ifndef SP_PROCESS_STATUS_H
+#define SP_PROCESS_STATUS_H
+
+#include <stdint.h>
+#include "sp_types.h"   /* sp_int */
+
+typedef struct sp_ProcessStatus_s {
+  sp_int pid;
+  sp_int status;   /* the raw waitpid(2) status word */
+} sp_ProcessStatus;
+
+/* Boxed new: takes pid + raw status word. Returns a sp_ProcessStatus *
+   on the GC heap. Raises TypeError on a non-Integer pid or negative
+   status. */
+sp_ProcessStatus *sp_process_status_new(sp_int pid, sp_int status);
+
+/* `$?`: the status of the last child waited for (Kernel#system, a
+   backtick, Process.wait*), or NULL -- nil -- before any. A new object on
+   each read, carrying the raw status word as it was stored. */
+sp_ProcessStatus *sp_last_process_status(void);
+
+/* A reader's receiver: NULL is nil, which has none of the readers, so it
+   raises NoMethodError ("undefined method 'exitstatus' for nil"). */
+sp_ProcessStatus *sp_process_status_recv(sp_ProcessStatus *p, const char *meth);
+
+/* to_s / inspect of a status, or of nil ("" / "nil") for NULL */
+const char *sp_process_status_str(sp_ProcessStatus *p, int is_inspect);
+
+/* Predicates. All return 0 or 1 except success_p, which is tri-state: -1
+   means CRuby's nil (the process did not exit normally). */
+int sp_process_status_exited_p(sp_int s);
+int sp_process_status_signaled_p(sp_int s);
+int sp_process_status_coredump_p(sp_int s);
+int sp_process_status_success_p(sp_int s);
+
+/* Accessors. CRuby semantics: exited? -> exitstatus, signaled? -> termsig;
+   the un-applicable accessor answers nil, carried as SP_INT_NIL -- the
+   nullable-Integer sentinel the rest of the runtime uses, so `p st.termsig`
+   renders nil and `st.termsig.nil?` is true. */
+sp_int sp_process_status_pid(sp_int s);
+sp_int sp_process_status_exitstatus(sp_int s);
+sp_int sp_process_status_termsig(sp_int s);
+
+/* Render the status to a string for to_s / inspect. The result lives
+   in a static buffer; the runtime copies it to a GC-heap string for
+   return. */
+const char *sp_process_status_to_s(sp_int pid, sp_int s, int is_inspect);
+
+/* Equality: two Process::Status values are equal iff their status
+   words are equal. pid is not compared. */
+int sp_process_status_eq(sp_int a, sp_int b);
+
+#endif

data/ext/qr_reader_native/sp_random.c

@@ -0,0 +1,287 @@
+/* sp_random.c -- the shared Kernel-level PRNG stream and the Random
+   instance methods (see sp_random.h). */
+#include <time.h>
+#include <string.h>
+#include "sp_random.h"
+#include "sp_crypto.h"   /* sp_crypto_entropy: the one secure source */
+#include "sp_alloc.h"
+#include <math.h>    /* isnan/isinf for the EDOM domain checks */   /* sp_str_alloc / sp_str_set_len / sp_float_to_s / sp_raise_cls / sp_gc_alloc */
+#include "sp_format.h"  /* sp_Range_inspect */
+#include "sp_str.h"     /* sp_sprintf (defined in the generated TU) */
+#include "sp_range.h"   /* sp_range_int_only */
+
+/* PCG-XSH-RR constants (64-bit state, 32-bit output). */
+#define SP_PCG_MULT 6364136223846793005ULL
+#define SP_PCG_INC  1442695040888963407ULL
+
+uint32_t sp_pcg32_adv(uint64_t *state) {
+  uint64_t old = *state;
+  *state = old * SP_PCG_MULT + SP_PCG_INC;
+  /* output: xorshift-high folds the state, then a random rotate */
+  uint32_t xs = (uint32_t)(((old >> 18u) ^ old) >> 27u);
+  uint32_t rot = (uint32_t)(old >> 59u);
+  return (xs >> rot) | (xs << ((32 - rot) & 31));
+}
+
+/* The PCG init sequence: zero the state, step, add the seed, then mix.
+   The extra mixing rounds keep nearby seeds from producing correlated
+   early output. */
+void sp_pcg_seed(uint64_t *state, uint64_t seed) {
+  *state = 0;
+  (void)sp_pcg32_adv(state);
+  *state += seed;
+  for (int i = 0; i < 10; i++) (void)sp_pcg32_adv(state);
+}
+
+/* Per-worker (SP_TLS) in the threaded build: the generator has no
+   internal lock, so a shared stream would race across workers. */
+static SP_TLS uint64_t sp_krand_state;
+static SP_TLS int sp_krand_seeded;
+
+void sp_krand_srand(uint64_t seed) {
+  sp_pcg_seed(&sp_krand_state, seed);
+  sp_krand_seeded = 1;
+}
+
+uint64_t sp_krand_next(void) {
+  if (!sp_krand_seeded) {
+    /* Auto-seed on first draw, mirroring CRuby's startup seeding so
+       unseeded rand/shuffle/sample vary per run. time() alone repeats
+       within a second; mix in clock() and the per-worker state address. */
+    sp_krand_srand((uint64_t)time(NULL) ^ ((uint64_t)clock() << 24) ^
+                   (uint64_t)(uintptr_t)&sp_krand_state);
+  }
+  uint64_t hi = sp_pcg32_adv(&sp_krand_state);
+  return (hi << 32) | sp_pcg32_adv(&sp_krand_state);
+}
+
+sp_int sp_krand_below(sp_int n) {
+  if (n <= 0) return 0;
+  /* uniform in [0, n) without modulo bias: reject draws below the
+     wrap-around threshold (0 for powers of two, so the loop is rare) */
+  uint64_t umax = (uint64_t)n;
+  uint64_t threshold = (uint64_t)(-(int64_t)umax) % umax;
+  uint64_t r;
+  do {
+    r = sp_krand_next();
+  } while (r < threshold);
+  return (sp_int)(r % umax);
+}
+
+sp_float sp_krand_float(void) {
+  return (sp_float)(sp_krand_next() >> 11) / (sp_float)(1ULL << 53);
+}
+
+/* ---- Random instance methods ---- */
+
+/* The default stream is a static, not a GC allocation -- but the class-method
+   forms (`Random.bytes`, `Random.rand`) hand it to the same entry points an
+   instance uses, and those root their receiver, which puts a .bss address on
+   the mark path. Lay a 0xfd skip byte directly before it so sp_gc_mark's
+   tag-byte protocol bails out instead of reading whatever precedes it as a GC
+   header: under SPINEL_GC_STRESS=1 that read reached a bogus scan hook and
+   crashed inside the mark walk. Same shape, and the same reason, as the root
+   fiber in sp_fiber.c: the guard array is exactly one alignment unit, so its
+   last byte always directly precedes the struct with no padding in between. */
+static SP_TLS struct { char guard[_Alignof(sp_Random)]; sp_Random r; } sp_random_default_box
+    = { .guard = { [_Alignof(sp_Random) - 1] = (char)0xfd } };
+#define sp_random_default (sp_random_default_box.r)
+uint64_t sp_random_next(sp_Random *r) {SP_GC_ROOT(r);
+  if (r == &sp_random_default) return sp_krand_next();
+  uint64_t hi = sp_pcg32_adv(&r->state);
+  return (hi << 32) | sp_pcg32_adv(&r->state);
+}
+sp_Random *sp_Random_new(sp_int seed) {
+  sp_Random *r = (sp_Random *)sp_gc_alloc(sizeof(sp_Random), NULL, NULL);
+  sp_pcg_seed(&r->state, (uint64_t)seed);
+  r->seed = seed;
+  return r;
+}
+/* Random#dup / #clone: a distinct generator that continues from the same state. */
+sp_Random *sp_Random_dup(sp_Random *r) {
+  if (!r) return NULL;   /* nil.dup is nil */
+  SP_GC_ROOT(r);
+  sp_Random *d = (sp_Random *)sp_gc_alloc(sizeof(sp_Random), NULL, NULL);
+  *d = *r;
+  return d;
+}
+/* Random.new(Float): CRuby truncates the float to an integer seed. A plain
+   (sp_int) cast is UB when the truncated value is out of range, so seed from
+   the in-range truncation when it fits and from the raw float bits otherwise
+   -- always deterministic (same float -> same stream), which is the actual
+   contract (the exact sequence is not MT19937 anyway). */
+sp_Random *sp_Random_new_float(sp_float f) {
+  uint64_t s;
+  if (f >= -9.2233720368547758e18 && f < 9.2233720368547758e18) {
+    s = (uint64_t)(int64_t)f;
+  }
+  else {
+    uint64_t bits; memcpy(&bits, &f, sizeof bits);
+    s = bits;
+  }
+  sp_Random *r = (sp_Random *)sp_gc_alloc(sizeof(sp_Random), NULL, NULL);
+  sp_pcg_seed(&r->state, s);
+  r->seed = (sp_int)s;
+  return r;
+}
+/* Random#seed: the seed the instance was constructed from. */
+sp_int sp_Random_seed(sp_Random *r) { return r ? r->seed : 0; }
+/* Random#== compares by internal state (two same-seed, same-position instances
+   are equal; advancing one makes them differ). */
+sp_bool sp_Random_eq(sp_Random *a, sp_Random *b) {
+  if (a == b) return TRUE;
+  if (!a || !b) return FALSE;
+  return (a->state == b->state && a->seed == b->seed) ? TRUE : FALSE;
+}
+/* Random.new with no seed: OS-entropy-ish auto seed. time() alone made two
+   instances created in the same second identical; mix in a per-thread counter
+   and the object address so every instance gets its own stream. */
+sp_Random *sp_Random_new_auto(void) {
+  static SP_TLS uint64_t sp_random_auto_ctr = 0;
+  sp_Random *r = (sp_Random *)sp_gc_alloc(sizeof(sp_Random), NULL, NULL);
+  uint64_t e = (((uint64_t)time(NULL)) << 20) ^ (++sp_random_auto_ctr * 0x9E3779B97F4A7C15ULL) ^
+               (uint64_t)(uintptr_t)r;
+  sp_pcg_seed(&r->state, e);
+  r->seed = (sp_int)(e >> 1);
+  return r;
+}
+/* Random#rand(Range): an integer in the (int-endpoint) range, empty raises. */
+sp_int sp_Random_rand_range(sp_Random *r, sp_Range rg) {SP_GC_ROOT(r);
+  sp_range_int_only(rg, "Random#rand");   /* (1..2.5): CRuby answers a Float */
+  /* an open side has no span: CRuby's Errno::EDOM, where the sentinel drew
+     from a span of the whole sp_int range */
+  if (rg.first == INTPTR_MIN || rg.last == INTPTR_MAX)
+    sp_raise_cls("Errno::EDOM", "Numerical argument out of domain");
+  sp_int lo = rg.first, hi = rg.excl ? rg.last - 1 : rg.last;
+  if (hi < lo) sp_raise_cls("ArgumentError", sp_sprintf("invalid argument - %s", sp_Range_inspect(&rg)));
+  if (!r) return lo;
+  return lo + (sp_int)(sp_random_next(r) % ((uint64_t)(hi - lo) + 1));
+}
+sp_int sp_Random_rand_int(sp_Random *r, sp_int n) {SP_GC_ROOT(r);
+  if (n <= 0) sp_raise_cls("ArgumentError", sp_sprintf("invalid argument - %lld", (long long)n));
+  if (!r) return 0;
+  return (sp_int)(sp_random_next(r) % (uint64_t)n);
+}
+sp_float sp_Random_rand_float(sp_Random *r) {SP_GC_ROOT(r);
+  if (!r) return 0.0;
+  return (sp_float)(sp_random_next(r) >> 11) / (sp_float)(1ULL << 53);
+}
+/* Random#rand(Float bound): a random Float in [0, bound). A non-positive bound
+   raises ArgumentError like the Integer form (MRI validates both). */
+sp_float sp_Random_rand_float_bound(sp_Random *r, sp_float bound) {SP_GC_ROOT(r);
+  /* CRuby 4: a non-finite bound is Errno::EDOM; a 0.0 bound draws in [0,1) (#3049) */
+  if (isnan(bound) || isinf(bound))
+    sp_raise_cls("Errno::EDOM", "Numerical argument out of domain");
+  if (bound == 0.0) return sp_Random_rand_float(r);
+  if (bound < 0) sp_raise_cls("ArgumentError", sp_sprintf("invalid argument - %s", sp_float_to_s(bound)));
+  return sp_Random_rand_float(r) * bound;
+}
+/* Class-method forms (`Random.rand` / `Random.bytes`) share the default
+   instance, mirroring CRuby's Random::DEFAULT. Its draws redirect to the
+   shared Kernel stream (see sp_random_next), which lazily self-seeds and
+   is per-worker in the threaded build. */
+sp_Random *sp_random_default_get(void) {
+  return &sp_random_default;
+}
+/* Random#bytes(n) -- n random bytes as a String, tagged ASCII-8BIT as CRuby
+   does. sp_str_set_len alone was not enough: #length counts UTF-8 units, and a
+   short draw is valid UTF-8 by chance often enough that Random.bytes(8).length
+   answered less than 8 about three times in a thousand. That is #3474, which
+   fixed urandom eight lines below and left this one. */
+const char *sp_Random_bytes(sp_Random *r, sp_int n) {SP_GC_ROOT(r);
+  if (n < 0) sp_raise_cls("ArgumentError", "negative string size (or size too big)");
+  char *b = sp_str_alloc((size_t)n);
+  for (sp_int i = 0; i < n; i++) b[i] = (char)(sp_random_next(r) & 0xff);
+  b[n] = 0;
+  sp_str_set_len(b, (size_t)n);
+  sp_str_mark_binary(b);
+  return b;
+}
+/* Random#rand(Float range): a Float in [lo, hi) (or [lo, hi] for an inclusive
+   range, though the float boundary is effectively open). */
+sp_float sp_Random_rand_float_range(sp_Random *r, sp_float lo, sp_float hi) {SP_GC_ROOT(r);
+  if (isnan(lo) || isinf(lo) || isnan(hi) || isinf(hi))
+    sp_raise_cls("Errno::EDOM", "Numerical argument out of domain");
+  return lo + sp_Random_rand_float(r) * (hi - lo);
+}
+/* Random.new_seed: a fresh nonneg seed drawn from the default stream. */
+sp_int sp_Random_new_seed(void) {
+  sp_int s = (sp_int)(sp_random_next(sp_random_default_get()) >> 1);
+  return s < 0 ? -s : s;
+}
+/* Random.urandom(n): n random bytes as a String (spinel has no real OS entropy
+   source wired up, so this draws from a freshly time-seeded stream). */
+const char *sp_Random_urandom(sp_int n) {
+  if (n < 0) sp_raise_cls("ArgumentError", "negative string size");
+  /* CRuby's Random.urandom IS the OS entropy source, and this was a PCG seeded
+     from time()/clock() -- a deterministic-per-run stand-in, from before the
+     tree had a real source. It does now: sp_crypto_entropy is the one place
+     that decides what counts as secure, and it fails closed. A caller of this
+     name is minting something that has to be unguessable. */
+  char *b = sp_str_alloc((size_t)n);
+  { sp_int off = 0;
+    while (off < n) {
+      int chunk = (int)((n - off) > SPC_RANDOM_MAX ? SPC_RANDOM_MAX : (n - off));
+      if (!sp_crypto_entropy((unsigned char *)b + off, chunk))
+        sp_raise_cls("RuntimeError", "Random.urandom: no secure random source available");
+      off += chunk;
+    }
+  }
+  b[n] = 0;
+  sp_str_set_len(b, (size_t)n);
+  /* CRuby hands back ASCII-8BIT, so #length is the byte count. Without the
+     mark, a short draw that happens to spell valid UTF-8 (about 1.5% of
+     4-byte draws) counted code points and answered short (#3474). */
+  sp_str_mark_binary(b);
+  return b;
+}
+/* Random#inspect / #to_s: CRuby's default object rendering (the seed is not
+   part of it; the address matches CRuby's zero-padded 16-digit form). */
+const char *sp_Random_inspect(sp_Random *r) {SP_GC_ROOT(r);
+  /* and its instance variables, as CRuby lists an object's */
+  void *t = sp_ivtbl_inspect_fn ? sp_ivtbl_get(r) : NULL;
+  if (t) return sp_sprintf("#<Random:0x%016llx%s>", (unsigned long long)(uintptr_t)r, sp_ivtbl_inspect_fn(t));
+  return sp_sprintf("#<Random:0x%016llx>", (unsigned long long)(uintptr_t)r);
+}
+/* Kernel#srand: seed the shared Kernel stream and remember the previous
+   seed, which srand returns (CRuby returns the prior seed, not the new
+   one). Every rand form -- bare/int/range, shuffle, sample, the Random
+   default instance -- draws from that one stream, so a single srand makes
+   them all reproducible. */
+static SP_TLS sp_int sp_kernel_seed = 0;
+sp_int sp_kernel_srand(sp_int seed) {
+  sp_int prev = sp_kernel_seed;
+  sp_kernel_seed = seed;
+  sp_krand_srand((uint64_t)seed);
+  return prev;
+}
+/* Random#rand(Bignum bound): a uniform Bigint in [0, bound). Composed from
+   32-bit chunks of the instance stream; accumulating two extra chunks past
+   the bound keeps the modulo bias around 2^-64. A non-positive bound raises
+   ArgumentError like the sp_int form (#3058). */
+typedef struct sp_Bigint sp_Bigint;
+extern sp_Bigint *sp_bigint_new_int(int64_t v);
+extern sp_Bigint *sp_bigint_mul(sp_Bigint *a, sp_Bigint *b);
+extern sp_Bigint *sp_bigint_add(sp_Bigint *a, sp_Bigint *b);
+extern sp_Bigint *sp_bigint_mod(sp_Bigint *a, sp_Bigint *b);
+extern int sp_bigint_cmp(sp_Bigint *a, sp_Bigint *b);
+extern const char *sp_bigint_to_s(sp_Bigint *b);
+sp_Bigint *sp_bigint_rand(sp_Random *r, sp_Bigint *bound) {SP_GC_ROOT(r);
+  SP_GC_ROOT(bound);
+  sp_Bigint *zero = sp_bigint_new_int(0);
+  SP_GC_ROOT(zero);
+  if (sp_bigint_cmp(bound, zero) <= 0)
+    sp_raise_cls("ArgumentError", sp_sprintf("invalid argument - %s", sp_bigint_to_s(bound)));
+  sp_Bigint *acc = zero;
+  SP_GC_ROOT(acc);
+  sp_Bigint *b32 = sp_bigint_new_int((int64_t)1 << 32);
+  SP_GC_ROOT(b32);
+  int extra = 2;
+  while (extra > 0) {
+    sp_Bigint *chunk = sp_bigint_new_int((int64_t)(sp_random_next(r) & 0xffffffffULL));
+    SP_GC_ROOT(chunk);
+    acc = sp_bigint_add(sp_bigint_mul(acc, b32), chunk);
+    if (sp_bigint_cmp(acc, bound) >= 0) extra--;
+  }
+  return sp_bigint_mod(acc, bound);
+}

data/ext/qr_reader_native/sp_random.h

@@ -0,0 +1,52 @@
+/* sp_random.h -- the shared Kernel-level PRNG stream (lib/sp_random.c).
+ *
+ * PCG-XSH-RR, the generator mruby's mruby-random uses: much better
+ * statistical quality than libc rand(), no cryptographic claims. One
+ * stream is shared by every runtime TU -- Kernel#rand/#srand, the array
+ * shuffle/sample paths (generated TU and libspinel_rt.a alike) and the
+ * Random default instance all draw from it, so a single `srand(n)`
+ * makes every consumer reproducible. */
+#ifndef SP_RANDOM_H
+#define SP_RANDOM_H
+
+#include <stdint.h>
+#include "sp_types.h"
+
+uint32_t sp_pcg32_adv(uint64_t *state);   /* one generator step */
+void sp_pcg_seed(uint64_t *state, uint64_t seed);
+uint64_t sp_krand_next(void);             /* 64-bit draw, lazily self-seeded */
+void sp_krand_srand(uint64_t seed);
+sp_int sp_krand_below(sp_int n);        /* uniform [0, n); 0 when n <= 0 */
+sp_float sp_krand_float(void);           /* uniform [0, 1) */
+
+/* Random -- per-instance PRNG. CRuby uses MT19937; spinel uses PCG-XSH-RR
+   (above), so the *sequence* differs from MRI -- MT19937 is not part of
+   the Ruby spec -- but each Random object keeps its own reproducible
+   stream from its seed. The default instance is a window onto the shared
+   Kernel stream, so srand() governs it too. */
+typedef struct { uint64_t state; sp_int seed; } sp_Random;
+/* The default instance is private to sp_random.c: it is a guarded static
+   there (see the comment on its box) and is reached only through
+   sp_random_default_get below. */
+uint64_t sp_random_next(sp_Random *r);
+sp_Random *sp_Random_new(sp_int seed);
+sp_Random *sp_Random_new_float(sp_float f);
+sp_Random *sp_Random_new_auto(void);
+sp_Random *sp_Random_dup(sp_Random *r);
+sp_int sp_Random_seed(sp_Random *r);
+sp_bool sp_Random_eq(sp_Random *a, sp_Random *b);
+sp_int sp_Random_rand_range(sp_Random *r, sp_Range rg);
+sp_int sp_Random_rand_int(sp_Random *r, sp_int n);
+struct sp_Bigint;
+struct sp_Bigint *sp_bigint_rand(sp_Random *r, struct sp_Bigint *bound);
+sp_float sp_Random_rand_float(sp_Random *r);
+sp_float sp_Random_rand_float_bound(sp_Random *r, sp_float bound);
+sp_float sp_Random_rand_float_range(sp_Random *r, sp_float lo, sp_float hi);
+sp_Random *sp_random_default_get(void);
+const char *sp_Random_bytes(sp_Random *r, sp_int n);
+sp_int sp_Random_new_seed(void);
+const char *sp_Random_urandom(sp_int n);
+const char *sp_Random_inspect(sp_Random *r);
+sp_int sp_kernel_srand(sp_int seed);
+
+#endif