docs(patches): carry jco #1574 — browser file read BigInt bounds coercion

Establish patches/jco/ + docs/upstream-patches.md as the
register for compatibility patches carried locally against
published upstream WASI / browser runtime layers.

Adds the first entry:

  Patch:               bytecodealliance/jco#1574
  Reason:              browser p2-shim file read BigInt bounds incompatibility
                       (Uint8Array.slice rejects the canonical-ABI BigInt
                       offset and length arguments)
  Scope:               JCO preview2/browser shim only
                       (packages/preview2-shim/lib/browser/filesystem.js
                       Descriptor.read)
  Removal condition:   first jco release containing #1574 or equivalent
                       upstream fix (detected at apply time via
                       'typeof offset === "bigint"' against the browser
                       filesystem.js source)
  Substrate impact:    none — patch lives in the compatibility layer,
                       not in any consumer's substrate code

Carried so that any consumer of @tegmentum/wasi-polyfill picks
up the corrected browser compatibility behavior without having
to learn about JCO's browser BigInt bug or carry a private
workaround.

Patch file applies with:
    patch -p5 -d <shim-dir> < patches/jco/1574-coerce-browser-file-read-bounds-to-numbers.patch

against a copy of @bytecodealliance/preview2-shim's browser
build (verified on 0.18.0).

See docs/upstream-patches.md for the active/retired patch
register and the lifecycle of a carried patch.

Signed-off-by: Zachary Whitley <zachary.whitley@tegmentum.ai>

Author: Zachary Whitley

docs/upstream-patches.md

@@ -0,0 +1,50 @@
+# wasi-polyfill — upstream patches register
+
+Local patches carried against published upstream WASI / browser
+runtime layers, with explicit removal conditions. These patches
+adapt **compatibility-layer behavior** — they are NOT Fiji
+substrate fixes and do not change Fiji's JVM/component
+semantics.
+
+## Architectural boundary
+
+| Layer | Responsibility |
+|---|---|
+| Fiji | JVM / component behavior |
+| **wasi-polyfill** | Runtime / browser / WASI compatibility |
+| Upstream (e.g. jco) | The published layer being patched |
+
+Patches in `wasi-polyfill/patches/` are *temporary* by design.
+Each has a documented **removal condition** keyed to the
+upstream's release stream. When that condition is met, the
+patch is dropped on the next maintenance pass.
+
+## Active patches
+
+### jco #1574 — browser p2-shim file read BigInt bounds
+
+- **Patch:** `wasi-polyfill/patches/jco/1574-coerce-browser-file-read-bounds-to-numbers.patch`
+- **Upstream:** [bytecodealliance/jco#1574](https://github.com/bytecodealliance/jco/pull/1574) (filed 2026-05-29; OPEN)
+- **Upstream issue:** [bytecodealliance/jco#1573](https://github.com/bytecodealliance/jco/issues/1573)
+- **Reason:** browser p2-shim file read BigInt bounds incompatibility (`Uint8Array.slice` rejects the canonical-ABI `BigInt` `offset` and `length` arguments)
+- **Scope:** JCO preview2 / browser shim only (`packages/preview2-shim/lib/browser/filesystem.js Descriptor.read`)
+- **Removal condition:** first `@bytecodealliance/preview2-shim` release containing #1574 or an equivalent upstream fix (detected at apply-time by `grep -q 'typeof offset === "bigint"'` against the browser `filesystem.js`)
+- **Fiji substrate impact:** **none**
+- **Applied by:** `scripts/portability/setup_beta13_browser.sh` (idempotent; skips if the upstream version already contains the fix)
+- **Carrying record opened:** 2026-05-29
+
+## How to retire a patch
+
+1. Upstream releases a version containing the fix.
+2. Update `package.json` `@bytecodealliance/preview2-shim` to that
+   version.
+3. Re-run `scripts/portability/setup_beta13_browser.sh` — the
+   detection grep matches and the patch is skipped cleanly.
+4. Delete the `.patch` file under `wasi-polyfill/patches/jco/`.
+5. Remove this section's entry from "Active patches" and add an
+   entry under "Retired patches" with the release version that
+   absorbed it.
+
+## Retired patches
+
+(none yet)

patches/jco/1574-coerce-browser-file-read-bounds-to-numbers.patch

@@ -0,0 +1,32 @@
+From: Zachary Whitley <zachary.whitley@tegmentum.ai>
+Subject: [PATCH] fix(p2-shim): coerce browser file read bounds to numbers
+
+Mirror of bytecodealliance/jco#1574. Apply locally against the
+@bytecodealliance/preview2-shim 0.18.0 browser implementation until
+the upstream fix ships in a published release.
+
+When applied via patch(1), use -p5 with a directory holding the
+browser shim copy:
+    patch -p5 -d <shim-dir> < 1574-coerce-browser-file-read-bounds-to-numbers.patch
+
+See wasi-polyfill/docs/upstream-patches.md for the carrying-record.
+
+---
+ packages/preview2-shim/lib/browser/filesystem.js | 4 +++-
+ 1 file changed, 3 insertions(+), 1 deletion(-)
+
+diff --git a/packages/preview2-shim/lib/browser/filesystem.js b/packages/preview2-shim/lib/browser/filesystem.js
+index 6c585ac1..6bf81913 100644
+--- a/packages/preview2-shim/lib/browser/filesystem.js
++++ b/packages/preview2-shim/lib/browser/filesystem.js
+@@ -188,7 +188,9 @@ class Descriptor {
+
+   read(length, offset) {
+     const source = getSource(this.#entry);
+-    return [source.slice(offset, offset + length), offset + length >= source.byteLength];
++    const off = typeof offset === "bigint" ? Number(offset) : offset;
++    const len = typeof length === "bigint" ? Number(length) : length;
++    return [source.slice(off, off + len), off + len >= source.byteLength];
+   }
+
+   write(buffer, offset) {