Merge remote-tracking branch 'origin/main' into kyo-net-coherent-closed-exceptions

Author: fwbrasil

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,7 @@
 <!--
 PRs require an approval from any of the core contributors, other than the PR author.
+CI on pull requests may require maintainer approval before it runs. To run CI yourself in the
+meantime, see "Running CI in Your Fork" in CONTRIBUTING.md.
 
 Include this header if applicable:
 Fixes #issue1, #issue2, ...
@@ -21,4 +23,5 @@ Add any important additional information as bullet points, such as:
 - Implementation details reviewers should know about
 - Open questions and concerns
 - Limitations
+- A link to a passing CI run in your fork, if you ran one (see "Running CI in Your Fork" in CONTRIBUTING.md)
 -->

.github/actions/setup/action.yml

@@ -89,6 +89,20 @@ runs:
       shell: bash
       run: bash scripts/apt-install.sh liburing-dev
 
+    # liburing is a build-time-only dependency of the kyo-net io_uring shim (kyo_uring.c), statically
+    # linked so the shipped artifact has no runtime liburing dependency. The JVM target compiles the shim
+    # via the kyo-ffi plugin's cc; the Native target links it through the Scala Native linker.
+    - name: Install liburing (Linux)
+      if: ${{ contains(inputs.os, 'linux') && (inputs.target == 'JVM' || inputs.target == 'Native') }}
+      uses: nick-fields/retry@v4
+      with:
+        max_attempts: 3
+        timeout_minutes: 5
+        retry_wait_seconds: 15
+        command: |
+          sudo apt-get update
+          sudo apt-get install -y -o Acquire::Retries=3 liburing-dev
+
     - name: Install podman (Linux)
       if: ${{ contains(inputs.os, 'linux') }}
       shell: bash

.github/workflows/build.yml

@@ -53,9 +53,11 @@ jobs:
     needs: prep
     # JVM full runs peak at ~95-100 min on Linux (browser/UI/caliban suites serialize under a
     # shared Chrome instance that cannot take concurrent CDP connections) and run slower on the
-    # Windows pole, where runner-slot contention has pushed a full JVM run past 180 min. 240 min
-    # bounds a genuine hang while giving the slowest pole real headroom.
-    timeout-minutes: 240
+    # Windows pole, where runner-slot contention has pushed a full JVM run past 180 min. The binding
+    # pole is the Native aggregate build+test on the slower linux-arm64 runner: linux-x64 Native
+    # completes in ~200 min, so arm64 needs headroom well past 240 min and hit the old cap. 360 min
+    # (the GitHub-hosted job ceiling) bounds a genuine hang while giving the slowest pole real headroom.
+    timeout-minutes: 360
     strategy:
       fail-fast: false
       max-parallel: 4
@@ -97,8 +99,7 @@ jobs:
       - uses: actions/checkout@v7.0.1
         with:
           # github.sha, not github.ref: a queued job must validate the commit that triggered the
-          # run, not whatever the branch tip is when the job starts. The concurrency group in
-          # ci.yml keys main pushes on the sha for the same reason.
+          # run, not whatever the branch tip is when the job starts.
           ref: ${{ inputs.ref || github.sha }}
           fetch-depth: 0
 

.github/workflows/ci.yml

@@ -58,14 +58,14 @@ on:
         required: false
         default: ''
 
-# A pull request keys its group on the PR number, so a new commit supersedes the in-flight run.
-# A push (to main) keys on the commit sha, so every commit gets its own group and is validated on
-# its own; cancel-in-progress only acts within a group, so a later push never cancels an earlier
-# main run.
+# Both pull requests and main pushes dedup their in-flight runs. A pull request keys on the PR
+# number, so a new commit supersedes the run still validating the previous one. A push to main
+# keys on the branch ref (github.ref is a constant refs/heads/main), so a newer push cancels an
+# earlier main run that is still pending or in progress; only the latest commit is validated.
 concurrency:
   # Custom-mode groups key on the run id (no dedup): the free-form command must never reach
   # the group name, where a multi-line value invalidates the workflow.
-  group: ci-${{ github.event.pull_request.number || github.sha }}-${{ inputs.mode }}-${{ inputs.targets }}-${{ inputs.oses }}-${{ inputs.mode == 'custom' && github.run_id || 0 }}-${{ inputs.custom-runner }}
+  group: ci-${{ github.event.pull_request.number || github.ref }}-${{ inputs.mode }}-${{ inputs.targets }}-${{ inputs.oses }}-${{ inputs.mode == 'custom' && github.run_id || 0 }}-${{ inputs.custom-runner }}
   cancel-in-progress: true
 
 jobs:
@@ -92,7 +92,11 @@ jobs:
             oses="$INPUT_OSES"
             targets="$INPUT_TARGETS"
           else
-            oses='linux-x64 linux-arm64 windows-x64'
+            # windows-x64 is temporarily excluded from push and pull_request runs while
+            # windows-specific failures are worked (container-backed kyo-pod tests do not run on
+            # the windows runner). It stays available on demand via workflow_dispatch with
+            # oses=windows-x64, which is how windows fixes are validated in the meantime.
+            oses='linux-x64 linux-arm64'
             targets='JVM JS Native Wasm'
           fi
 

.github/workflows/deploy-site.yml

@@ -26,6 +26,7 @@ concurrency:
 
 jobs:
   build:
+    if: github.repository == 'getkyo/kyo'
     runs-on: ubuntu-latest
     env:
       JAVA_OPTS: -Xms3G -Xmx4G -Xss10M -XX:MaxMetaspaceSize=512M
@@ -39,6 +40,23 @@ jobs:
         with:
           jvm: corretto:25
           apps: sbt
+      # The site reaches kyo-net through kyo-http, so rendering it compiles kyo-net's C shims. This
+      # workflow does not use .github/actions/setup, so the native build deps are installed here, as
+      # readme.yml does for the same reason.
+      #
+      # liburing (build-time only): the io_uring shim (kyo_uring.c) statically links -luring.
+      - name: Install liburing (Linux)
+        run: bash scripts/apt-install.sh liburing-dev
+      # BoringSSL has to be staged, not stubbed. Without the staged tree build.sbt compiles the
+      # c-boringssl-stub shim, and kyo-net's `Compile / packageBin` runs kyoNetNativeClassifierGuard
+      # (build.sbt), which fails on a stub. The site render needs kyo-net's packageBin, so it trips
+      # the guard even though it publishes nothing.
+      - name: Prepare BoringSSL
+        shell: bash
+        run: |
+          command -v cmake >/dev/null 2>&1 || bash scripts/apt-install.sh cmake
+          command -v go >/dev/null 2>&1 || bash scripts/apt-install.sh golang-go
+          bash kyo-net/build/boringssl/build-boringssl.sh linux-x86_64
       - name: Link the browser bundle (fullLinkJS)
         run: sbt 'kyo-website-bundleJS/Compile/fullLinkJS'
       - name: Render and assemble the site from the current repo
@@ -48,6 +66,7 @@ jobs:
           path: site
   deploy:
     needs: build
+    if: github.repository == 'getkyo/kyo'
     runs-on: ubuntu-latest
     environment:
       name: github-pages

.github/workflows/release-probe.yml

@@ -18,6 +18,8 @@ name: release-probe
 on:
   pull_request:
     branches: [main]
+  push:
+    branches: [main]
 
 permissions:
   contents: read
@@ -30,6 +32,11 @@ concurrency:
 
 jobs:
   probe:
+    # release.yml already builds the release artifacts on an upstream main push, so there the probe
+    # only needs to run for pull requests. In a fork release.yml is guarded off, so the probe also
+    # runs on pushes to the fork's main to keep publishability checked. On an upstream main push the
+    # guard skips the job, so no runner is used and the run entry is inert.
+    if: github.event_name == 'pull_request' || github.repository != 'getkyo/kyo'
     runs-on: ubuntu-latest
     timeout-minutes: 120
     env:

.github/workflows/release.yml

@@ -24,10 +24,11 @@ jobs:
   # clang emit x86_64 code.
   natives-darwin:
     if: |
-      (github.event_name == 'push') ||
-      (github.event_name == 'issue_comment' &&
-       github.event.issue.pull_request &&
-       github.event.comment.body == '/release')
+      github.repository == 'getkyo/kyo' && (
+        (github.event_name == 'push') ||
+        (github.event_name == 'issue_comment' &&
+         github.event.issue.pull_request &&
+         github.event.comment.body == '/release'))
     runs-on: macos-14
     env:
       JAVA_OPTS: -Xms4G -Xmx4G -XX:ReservedCodeCacheSize=256M
@@ -71,7 +72,7 @@ jobs:
             test -s "kyonet-natives/$f" || { echo "producer natives-darwin is missing $f" >&2; exit 1; }
           done
           ls -l kyonet-natives
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: natives-darwin
           path: kyonet-natives
@@ -83,10 +84,11 @@ jobs:
   # run on the glibc host so they use the runner's Node; only the build runs in the container.
   natives-linux-x86_64:
     if: |
-      (github.event_name == 'push') ||
-      (github.event_name == 'issue_comment' &&
-       github.event.issue.pull_request &&
-       github.event.comment.body == '/release')
+      github.repository == 'getkyo/kyo' && (
+        (github.event_name == 'push') ||
+        (github.event_name == 'issue_comment' &&
+         github.event.issue.pull_request &&
+         github.event.comment.body == '/release'))
     runs-on: ubuntu-latest
     env:
       JAVA_OPTS: -Xms4G -Xmx4G -XX:ReservedCodeCacheSize=256M
@@ -138,7 +140,7 @@ jobs:
             test -s "kyonet-natives/$f" || { echo "producer natives-linux-x86_64 is missing $f" >&2; exit 1; }
           done
           ls -l kyonet-natives
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: natives-linux-x86_64
           path: kyonet-natives
@@ -148,10 +150,11 @@ jobs:
   # the same Alpine step on the arm64 host (the temurin alpine image is multi-arch).
   natives-linux-aarch64:
     if: |
-      (github.event_name == 'push') ||
-      (github.event_name == 'issue_comment' &&
-       github.event.issue.pull_request &&
-       github.event.comment.body == '/release')
+      github.repository == 'getkyo/kyo' && (
+        (github.event_name == 'push') ||
+        (github.event_name == 'issue_comment' &&
+         github.event.issue.pull_request &&
+         github.event.comment.body == '/release'))
     runs-on: ubuntu-24.04-arm
     env:
       JAVA_OPTS: -Xms4G -Xmx4G -XX:ReservedCodeCacheSize=256M
@@ -200,7 +203,7 @@ jobs:
             test -s "kyonet-natives/$f" || { echo "producer natives-linux-aarch64 is missing $f" >&2; exit 1; }
           done
           ls -l kyonet-natives
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: natives-linux-aarch64
           path: kyonet-natives
@@ -209,10 +212,11 @@ jobs:
   publish:
     needs: [natives-darwin, natives-linux-x86_64, natives-linux-aarch64]
     if: |
-      (github.event_name == 'push') ||
-      (github.event_name == 'issue_comment' &&
-       github.event.issue.pull_request &&
-       github.event.comment.body == '/release')
+      github.repository == 'getkyo/kyo' && (
+        (github.event_name == 'push') ||
+        (github.event_name == 'issue_comment' &&
+         github.event.issue.pull_request &&
+         github.event.comment.body == '/release'))
     runs-on: ubuntu-latest
     env:
       JAVA_OPTS: -Xms4G -Xmx4G -XX:ReservedCodeCacheSize=256M
@@ -230,7 +234,7 @@ jobs:
       # host's). merge-multiple flattens the per-producer artifacts into one directory; the filenames
       # (lib<id>-<os>-<arch>.<ext>) are unique across producers, so nothing collides.
       - name: Download producer natives into ffiPrebuiltDir
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           pattern: natives-*
           path: kyonet-prebuilt

.gitignore

@@ -5,6 +5,9 @@
 .metals
 project/target
 project/project
+project/.boot
+project/.ivy
+project/.sbtboot
 .vscode
 target
 *.log

AGENTS.md

@@ -187,7 +187,7 @@ To create or rewrite a module's README, invoke the `/readme <module-path>` skill
 
 ## Common Gotchas
 
-1. **`kyo.System` shadows `java.lang.System`**: use fully qualified `java.lang.System` when needed
+1. **`kyo.System` shadows `java.lang.System`**, and **`kyo.SecureRandom` shadows `java.security.SecureRandom`**: use the fully qualified JDK name when both are in scope
 2. **Effect handlers are not inline**: `Abort.run`, `Var.run` are regular methods; only suspend/create methods are inline
 3. **`Frame` required on every effectful method**, but not on pure data accessors like `capacity` or `size`
 4. **Overloads delegate to canonical**: never duplicate logic across method variants

CONTRIBUTING.md

@@ -8,6 +8,7 @@ Thank you for considering contributing to this project! We welcome all contribut
   - [Getting Started](#getting-started)
   - [Configuring Java Options](#configuring-java-options)
   - [How to Build Locally](#how-to-build-locally)
+  - [Running CI in Your Fork](#running-ci-in-your-fork)
   - [Adding a New API](#adding-a-new-api)
   - [LLM Use Guide](#llm-use-guide)
 - [Core Principles](#core-principles)
@@ -129,6 +130,20 @@ Check formatting before submitting:
 sbt "scalafmtCheckAll"
 ```
 
+### Running CI in Your Fork
+
+Pull requests to the main repository currently require maintainer approval before CI runs, so checks may not start right away. To get full CI signal on your own schedule, run the same workflows in your fork. They use only GitHub-hosted runners that are free for public repositories and read no repository secrets, so they run unmodified.
+
+1. **Enable Actions on your fork.** GitHub disables a fork's workflows by default. Open your fork's **Actions** tab (`https://github.com/<your-user>/<your-fork>/actions`) and enable them when prompted.
+
+2. **Run the `ci` workflow.** In the **Actions** tab, select **ci** and click **Run workflow**, then choose your branch. Set **oses** to `linux-x64 linux-arm64` to match what pull-request CI runs. Leave **mode** as `full` for a complete run, or set it to `diff` to test only the modules your branch changed. The Windows pole is not part of PR CI; add `windows-x64` to **oses** to include it.
+
+3. **Or open a fork-internal pull request.** A PR from your working branch against your fork's own `main` triggers the same diff-mode run an upstream PR would, on your runners, with no approval needed. It also runs `release-probe`, a no-secrets publishability check, for free.
+
+Diff mode compares against your fork's `main`, so sync your fork before a diff-mode run (the **Sync fork** button, or `git fetch upstream && git push origin main`) to match upstream. The first run is slower while the runner caches warm up.
+
+When you open your pull request, include a link to the fork CI run if you have one, so reviewers can see the result.
+
 ### Adding a New API
 
 If you want to contribute a new method or type, feel free to:
@@ -243,11 +258,16 @@ When a Kyo primitive exists for a concept, use it instead of the stdlib equivale
 | `Result[E, A]` | `Either`, `Try`                                            | Three-way: `Success`/`Failure`/`Panic` — never raw `Either` or `Try` in effect signatures                                                                                                        |
 | `Chunk[A]`     | `Seq`, `List`, `Vector`                                    | Use internally; accept generic collections in public APIs (see below)                                                                                                                            |
 | `Duration`     | `java.time.Duration`, `scala.concurrent.duration.Duration` | Opaque `Long`-based, zero-allocation                                                                                                                                                             |
+| `ByteSize`     | a bare `Long` or `Int` holding a byte count                | Opaque `Long`-based, zero-allocation, saturating arithmetic, non-negative by construction                                                                                                        |
 | `Instant`      | `java.time.Instant`                                        | Kyo's own wrapper with consistent API                                                                                                                                                            |
 | `Span[A]`      | `IArray[A]`, `ArraySeq[A]`                                 | Immutable array wrapper, avoids boxing, O(1) indexing                                                                                                                                            |
 | `Schedule`     | Custom retry/timing logic                                  | Composable scheduling policies                                                                                                                                                                   |
 | `TypeMap[A]`   | Heterogeneous maps                                         | Type-safe map keyed by type                                                                                                                                                                      |
 
+Prefer `ByteSize` over a bare numeric type wherever a value means "a quantity of bytes": storage and disk sizes, file sizes, buffer and byte-array capacities, read and write chunk sizes, network packet and frame sizes, transfer limits and quotas, memory footprints. It carries the unit in the type, so a call site cannot silently pass kibibytes where bytes were expected, and its arithmetic saturates instead of overflowing. A raw `Long` or `Int` stays correct for an index, an offset into a buffer, or a count of elements; those are positions, not sizes.
+
+This is guidance for new and changed code. Existing APIs that thread byte counts as `Long` are not required to migrate, and a migration should be its own change rather than a drive-by edit inside an unrelated one.
+
 **kyo-prelude** — effects:
 
 | Kyo primitive | Purpose              | Notes                                                               |