feat(stdlib/json): v0.3 — RSR rewire to hpm-json-rsr Zig FFI (#421)

## Summary

Completes the long-deferred `parse: String -> Option<HpmJsonValue>`
bridge in `stdlib/json.affine` by routing through the
**`hyperpolymath/hpm-json-rsr` Zig FFI** (11 exports) instead of
hand-rolling a parser. Closes the echidna#63 "parse bridge" gap and
unblocks the OikosBot AffineScript port's webhook payload extraction
(oikos#41 + `bot-integration-affine/`).

### What lands

- **`stdlib/json.affine` v0.3** — opaque `pub extern type HpmJsonValue`
+ 11 `hpm_json_*` externs mirroring the Zig exports verbatim, plus:
- `pub fn parse(src: String) -> Option<HpmJsonValue>` (handle-returning;
caller owns + must free)
- `pub fn to_json(val: HpmJsonValue) -> Option<Json>` (tree-walk;
materialises leaves + arrays; objects descend lazily via
`hpm_json_object_get`)
- **`lib/codegen_deno.ml`** — Deno-ESM lowering: 11 entries in
`deno_builtins` mapping `hpm_json_*` → `__as_hpmJson*` JS shims (handle
== JS value; `JSON.parse` powers `hpm_json_parse`; `hpm_json_free` is a
no-op since GC reclaims).

### Object-key enumeration gap

The Zig FFI does not (yet) export an `hpm_json_object_keys` function, so
`to_json` cannot materialise objects into a full `JObject(...)` sum.
This is honest: object payloads (e.g. GitHub webhooks) descend lazily by
known key via `hpm_json_object_get` + leaf-extract — exactly how the
OikosBot port needs to use it. A follow-up PR to `hpm-json-rsr` will add
`hpm_json_object_keys` to close the round-trip.

### Verification

- ✅ `affinescript check stdlib/json.affine` — type checks
- ✅ `dune build` — clean
- ✅ `dune runtest` — same 2 pre-existing failures as `main`, no
regressions
- ✅ Runtime smoke (Deno-ESM): object descent
(`{"installation":{"id":12345}}` → `12345`), array materialisation
(`[1,2,3]` → `JArray`), malformed JSON → `None`

### Vocabulary

"Zig FFI" not "C-ABI" — the wire-level C calling convention is an
implementation detail of Zig's `export fn`. Estate convention is
Zig=FFIs / Idris2=ABIs.

## Test plan

- [ ] Type check still passes after rebase (`affinescript check
stdlib/json.affine`)
- [ ] No regression on the test suite delta
- [ ] Deno-ESM smoke driver (in PR body / follow-up test) exercises
object descent + array materialisation + malformed input

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

CHANGELOG.md

@@ -20,6 +20,7 @@ this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- feat(stdlib/json): v0.3 — RSR rewire to `hpm-json-rsr` Zig FFI (11 externs + opaque `HpmJsonValue` + `parse` / `to_json`), Deno-ESM lowering via `__as_hpmJson*` shims (#421)
 - feat(parser): trailing-comma in fn params and expr lists (Refs gitbot-fleet#148) (#370)
 - feat(lexer): underscore-prefix idents `_key`/`_unused` (Refs gitbot-fleet#148) (#373)
 - feat(parser): record-update spread at start `#{ ..base, f: v }` (Refs gitbot-fleet#148) (#376)

lib/codegen_deno.ml

@@ -209,6 +209,57 @@ const __as_httpHeadersFromResponse = (res) => {
   res.headers.forEach((value, key) => out.push([key, value]));
   return out;
 };
+// ---- hpm-json-rsr Zig FFI shims (stdlib/json.affine v0.3) ----
+// `HpmJsonValue` is opaque to AffineScript; on Deno-ESM it's just the
+// underlying JS value from JSON.parse. The shims mirror the sentinel
+// conventions of the Zig exports so the AffineScript-side wrappers
+// (`to_json`, `parse`) behave identically across backends.
+const __as_hpmJsonParse = (s) => {
+  try { return Some(JSON.parse(String(s))); } catch (_e) { return None; }
+};
+const __as_hpmJsonFree = (_v) => 0;
+const __as_hpmJsonType = (v) => {
+  if (v === null || v === undefined) return 0;
+  if (typeof v === "boolean") return 1;
+  if (typeof v === "number")  return Number.isInteger(v) ? 2 : 3;
+  if (typeof v === "string")  return 4;
+  if (Array.isArray(v))       return 5;
+  if (typeof v === "object")  return 6;
+  return -1;
+};
+const __as_hpmJsonBool = (v) => (typeof v === "boolean" ? (v ? 1 : 0) : -1);
+const __as_hpmJsonInt = (v) =>
+  (typeof v === "number" ? Math.trunc(v) : Number.MIN_SAFE_INTEGER);
+const __as_hpmJsonFloat = (v) => (typeof v === "number" ? v : NaN);
+const __as_hpmJsonString = (v) => (typeof v === "string" ? v : "");
+const __as_hpmJsonObjectGet = (v, k) => {
+  if (v === null || typeof v !== "object" || Array.isArray(v)) return None;
+  return Object.prototype.hasOwnProperty.call(v, String(k))
+    ? Some(v[String(k)]) : None;
+};
+const __as_hpmJsonArrayLen = (v) => (Array.isArray(v) ? v.length : 0);
+const __as_hpmJsonArrayGet = (v, i) => {
+  if (!Array.isArray(v)) return None;
+  const idx = Number(i);
+  return (idx >= 0 && idx < v.length) ? Some(v[idx]) : None;
+};
+const __as_hpmJsonEscapeString = (s) => {
+  let out = "";
+  const src = String(s);
+  for (let i = 0; i < src.length; i++) {
+    const c = src.charCodeAt(i);
+    if (c === 0x22) out += "\\\"";
+    else if (c === 0x5c) out += "\\\\";
+    else if (c === 0x0a) out += "\\n";
+    else if (c === 0x0d) out += "\\r";
+    else if (c === 0x09) out += "\\t";
+    else if (c === 0x08) out += "\\b";
+    else if (c === 0x0c) out += "\\f";
+    else if (c < 0x20) out += "\\u00" + c.toString(16).padStart(2, "0");
+    else out += src[i];
+  }
+  return out;
+};
 const __as_httpFetch = async (url, method, headers, bodyOpt) => {
   const init = { method, headers: __as_httpHeadersToObject(headers) };
   if (bodyOpt && bodyOpt.tag === "Some") init.body = bodyOpt.value;
@@ -320,7 +371,19 @@ let () =
      (see {!fd_is_async}). *)
   b "http_request" (fun a ->
     Printf.sprintf "(await __as_httpFetch(%s, %s, %s, %s))"
-      (arg 0 a) (arg 1 a) (arg 2 a) (arg 3 a))
+      (arg 0 a) (arg 1 a) (arg 2 a) (arg 3 a));
+  (* ---- hpm-json-rsr Zig FFI surface (stdlib/json.affine v0.3) ---- *)
+  b "hpm_json_parse"         (fun a -> Printf.sprintf "__as_hpmJsonParse(%s)" (arg 0 a));
+  b "hpm_json_free"          (fun a -> Printf.sprintf "__as_hpmJsonFree(%s)" (arg 0 a));
+  b "hpm_json_type"          (fun a -> Printf.sprintf "__as_hpmJsonType(%s)" (arg 0 a));
+  b "hpm_json_bool"          (fun a -> Printf.sprintf "__as_hpmJsonBool(%s)" (arg 0 a));
+  b "hpm_json_int"           (fun a -> Printf.sprintf "__as_hpmJsonInt(%s)" (arg 0 a));
+  b "hpm_json_float"         (fun a -> Printf.sprintf "__as_hpmJsonFloat(%s)" (arg 0 a));
+  b "hpm_json_string"        (fun a -> Printf.sprintf "__as_hpmJsonString(%s)" (arg 0 a));
+  b "hpm_json_object_get"    (fun a -> Printf.sprintf "__as_hpmJsonObjectGet(%s, %s)" (arg 0 a) (arg 1 a));
+  b "hpm_json_array_len"     (fun a -> Printf.sprintf "__as_hpmJsonArrayLen(%s)" (arg 0 a));
+  b "hpm_json_array_get"     (fun a -> Printf.sprintf "__as_hpmJsonArrayGet(%s, %s)" (arg 0 a) (arg 1 a));
+  b "hpm_json_escape_string" (fun a -> Printf.sprintf "__as_hpmJsonEscapeString(%s)" (arg 0 a))
 
 (* ============================================================================
    Identifier sanitisation (JS reserved words -> trailing underscore)

stdlib/json.affine

@@ -16,11 +16,17 @@
 // object feeds `dict::get` directly.
 //
 // Scope (echidna#63 "What is needed"): the `Json` type, the decode_*
-// and encode_* combinators, and `stringify`. The String->Json *parse*
-// bridge is deliberately out of scope here — it belongs at the
-// echidna#61 `Http` boundary (`Response.json : Async[Json]`), where the
-// host fetch result crosses in; tracked there, not duplicated as a
-// hand-rolled parser in stdlib.
+// and encode_* combinators, and `stringify`.
+//
+// v0.3 (this revision) — adds the `parse` bridge as a thin wrapper
+// over the `hyperpolymath/hpm-json-rsr` Zig FFI surface (11 exports).
+// The wrapper does NOT hand-roll a JSON parser: `hpm_json_parse`
+// owns parsing + arena allocation, and AffineScript-side functions
+// tree-walk the resulting opaque `HpmJsonValue` handle into the AS
+// `Json` sum type for leaves + arrays. Object-key enumeration is
+// not yet exposed by the Zig FFI — see `to_json` for the gap, and
+// prefer the lazy `hpm_json_object_get` + leaf-extract pattern for
+// object payloads (e.g. GitHub webhook JSON).
 
 module json;
 
@@ -203,6 +209,106 @@ fn escape_string(s: String) -> String {
   out ++ "\""
 }
 
+// ============================================================================
+// RSR rewire (v0.3) — hpm-json-rsr Zig FFI bindings
+//
+// The 11 `hpm_json_*` externs faithfully mirror the Zig exports at
+// `hyperpolymath/hpm-json-rsr/ffi/zig/src/main.zig`. They lower on the
+// Deno-ESM backend (lib/codegen_deno.ml) to `JSON.parse` + JS-native
+// walks (a handle is just the underlying JS value); on native targets
+// they map to FFI into the hpm-json-rsr cdylib.
+//
+// HpmJsonValue is an opaque, host-managed handle. Pair every Some(h)
+// from `parse` / `hpm_json_object_get` / `hpm_json_array_get` with a
+// matching `hpm_json_free(h)` to release the arena (no-op on JS, real
+// free on native).
+//
+// Sentinel conventions (faithful to the Zig surface):
+//   hpm_json_type   -> 0=null 1=bool 2=int 3=float 4=string 5=array 6=object; -1 on null val
+//   hpm_json_bool   -> 0/1; -1 on type mismatch
+//   hpm_json_int    -> INT64_MIN on type mismatch
+//   hpm_json_float  -> NaN on type mismatch
+//
+// Object-key enumeration is NOT yet a Zig export; consequently `to_json`
+// returns None for HpmJsonValue roots whose type tag is 6 (object). For
+// object payloads, descend lazily via `hpm_json_object_get`.
+// ============================================================================
+
+pub extern type HpmJsonValue;
+
+pub extern fn hpm_json_parse(src: String) -> Option<HpmJsonValue>;
+pub extern fn hpm_json_free(val: HpmJsonValue) -> Int;
+pub extern fn hpm_json_type(val: HpmJsonValue) -> Int;
+pub extern fn hpm_json_bool(val: HpmJsonValue) -> Int;
+pub extern fn hpm_json_int(val: HpmJsonValue) -> Int;
+pub extern fn hpm_json_float(val: HpmJsonValue) -> Float;
+pub extern fn hpm_json_string(val: HpmJsonValue) -> String;
+pub extern fn hpm_json_object_get(val: HpmJsonValue, key: String) -> Option<HpmJsonValue>;
+pub extern fn hpm_json_array_len(val: HpmJsonValue) -> Int;
+pub extern fn hpm_json_array_get(val: HpmJsonValue, idx: Int) -> Option<HpmJsonValue>;
+pub extern fn hpm_json_escape_string(src: String) -> String;
+
+/// Parse `src` into an owning RSR handle, or `None` on malformed JSON.
+/// Caller MUST pair every returned `Some(h)` with `hpm_json_free(h)`
+/// to release the underlying parsed arena. (No-op on Deno-ESM, real
+/// arena-free on native.)
+pub fn parse(src: String) -> Option<HpmJsonValue> {
+  hpm_json_parse(src)
+}
+
+/// Tree-walk a non-object `HpmJsonValue` into the AS `Json` sum.
+///
+/// Returns `None` if the value's root is an object (tag 6) — see the
+/// module preamble: object-key enumeration is not yet exported by the
+/// Zig FFI. Leaves + arrays of leaves/arrays materialise fully.
+///
+/// Recursively `hpm_json_free`s every child handle the walk allocates;
+/// the root handle is the caller's responsibility (matches the parse
+/// ownership contract).
+pub fn to_json(val: HpmJsonValue) -> Option<Json> {
+  let t = hpm_json_type(val);
+  if t == 0 {
+    Some(JNull)
+  } else if t == 1 {
+    Some(JBool(hpm_json_bool(val) == 1))
+  } else if t == 2 {
+    Some(JInt(hpm_json_int(val)))
+  } else if t == 3 {
+    Some(JFloat(hpm_json_float(val)))
+  } else if t == 4 {
+    Some(JString(hpm_json_string(val)))
+  } else if t == 5 {
+    let n = hpm_json_array_len(val);
+    let mut acc = [];
+    let mut i = 0;
+    while i < n {
+      match hpm_json_array_get(val, i) {
+        Some(child) => {
+          match to_json(child) {
+            Some(j) => {
+              acc = acc ++ [j];
+              hpm_json_free(child);
+            },
+            None => {
+              hpm_json_free(child);
+              return None;
+            }
+          }
+        },
+        None => {
+          return None;
+        }
+      };
+      i = i + 1;
+    }
+    Some(JArray(acc))
+  } else {
+    // tag 6 (object) — no key-enumeration in the Zig FFI yet;
+    // tag -1 (null val) — defensive: shouldn't reach here.
+    None
+  }
+}
+
 /// Serialise a `Json` value to a compact JSON string.
 pub fn stringify(j: Json) -> String {
   match j {