pkgs.ml
Activity Stats For agents Log in with GitHub

kernel

v0.0.43

Platform abstraction layer for Riot

Repository Open docs Open in playground
Install
riot add kernel
riot.toml
kernel = "0.0.43"
Last release
May 15, 2026
License
Apache-2.0
Dependencies
0
Dependents
6
Installs
151
Published versions
33
Owner
@leostera@leostera
README Expand

kernel-new

kernel-new is Riot's new platform abstraction layer.

It is intentionally narrow:

  • portable public contracts over platform-specific implementations
  • just enough foundational types for std to build on top of it
  • Riot-authored native shims under native/

Current backend status:

  • Unix only

Current public surface:

  • foundational: Bool, Char, Int, Int32, Int64, Float, String, Bytes, Array, Option, Result, SystemError, Error
  • runtime/platform: Effect, Async, Path, IO.Iovec, Fs.File, Fs.ReadDir, Net.Addr, Net, Time, Env, Process

Not in kernel-new:

  • Reader / Writer
  • public raw file descriptors or socket handles
  • iterators, regex, crypto, compression, unicode, vectors, maps

Error Model

Each public module owns a small typed error type.

Examples:

  • Fs.File.error
  • Fs.ReadDir.error
  • Net.Addr.error
  • Net.TcpStream.error
  • Net.UdpSocket.error
  • Time.SystemTime.error
  • Time.Monotonic.error

Kernel_new.Error wraps those module-local errors into one shared sum type for package boundaries and test helpers. Kernel_new.SystemError owns the shared errno-like system cases used by native shims.

Kernel_new.Error is only the typed envelope. The invariant-violation escape hatch stays in Kernel_new.SystemError.panic, not in the package error sum.

Kernel_new.SystemError is intentionally symbolic. Numeric error-code bridges stay internal to native-facing modules and do not belong in the portable public contract.

Rules

  • Do not depend on Unix.* or Stdlib.* in kernel-new implementation code.
  • Keep native code in native/.
  • Keep public APIs portable even when the backend is Unix-only today.
  • Prefer structured errors over stringly errors or native exceptions.
  • If an operation has a real async/readiness path, prefer exposing that path instead of a blocking helper. Fast metadata-style syscalls are still fine when they are inherently synchronous.
  • Keep source-layout and code-hygiene checks out of unit tests. Those rules belong in docs or separate tooling because tests may run without source access.
  • Do not add Backend.ml shim modules. Use local backend files like env/unix.ml where the planner supports them; otherwise keep the implementation in the public module until the nested-backend layout is supported cleanly.

Backend Layout

Platform-backed public modules should prefer a local backend layout:

  • fs/file/file.ml re-exports the selected backend with include Unix
  • fs/file/unix.ml holds the Unix implementation
  • future backends should live beside it, such as windows.ml or wasi.ml

Use the same pattern for other platform-backed directory modules:

  • async/adapter/adapter.ml and async/adapter/unix.ml
  • env/env.ml and env/unix.ml
  • process/process.ml and process/unix.ml
  • time/system_time/system_time.ml and time/system_time/unix.ml
  • time/monotonic/monotonic.ml and time/monotonic/unix.ml
  • net/tcp_listener/tcp_listener.ml and net/tcp_listener/unix.ml
  • net/tcp_stream/tcp_stream.ml and net/tcp_stream/unix.ml
  • net/udp_socket/udp_socket.ml and net/udp_socket/unix.ml

Keep pure modules pure. Do not add backend files where the code is platform-free today:

  • IO.Iovec
  • Net.SocketAddr

Net.IpAddr currently uses a Riot-owned native validator, so it follows the local backend pattern even though its public surface stays small and pure-looking.

Public Surface Notes

  • Keep public handles abstract. Fs.File.t, Net.TcpStream.t, Net.UdpSocket.t, Process.t, and the clock/timer handles should stay opaque.
  • Keep the package error story layered: local module error first, SystemError.t for shared native/system failures, and Kernel_new.Error.t for package boundaries.
  • IO is intentionally small. Its public role is IO.Iovec; generic catch-all I/O error aliases do not belong there.
  • Async.Adapter and Async.Source.make are backend-facing seams used by kernel-new itself. Consumers should prefer Async.Poll plus to_source values from public modules.
  • Readiness-backed and intentionally synchronous behavior notes should live in the relevant .mli next to the APIs they describe, not only in package-level docs.
  • If a capability has a to_source, do not add a separate blocking wait helper for it.
  • Any new external should be documented in code as either readiness-backed or intentionally synchronous.

Review Checklist

  • no public raw file descriptors, socket handles, timer ids, or process-owned native handles
  • no blocking helper where readiness plus to_source already exists
  • local backend modules use file.ml or module.ml as the public re-export and keep backend code in sibling files like unix.ml
  • public errors stay typed and structured; string messages are for to_string output, not API contracts

For std

std should treat kernel-new as the portability substrate, not as a complete user-facing I/O library.

The intended seams are:

  • Fs.File.to_source, Net.*.to_source, and Process.to_source for actor-friendly waiting
  • Fs.ReadDir for incremental directory iteration without raw OS handles
  • Net.Addr for hostname-to-SocketAddr resolution above raw IP parsing
  • try_wait instead of a blocking process wait
  • IO.Iovec for vectored file and socket operations
  • SystemTime and Monotonic as raw clock primitives, with richer time APIs above

Validate

timeout 30 riot build kernel-new
timeout 180 riot test -p kernel-new
timeout 180 riot bench -p kernel-new --json

Benchmarks

See bench/README.md for the current benchmark set and baseline medians.

Installs
Downloads over the last 30 days, stacked by release.
Total installs
151
Downloads over the last 30 days
v0.0.4310
v0.0.423
v0.0.411
v0.0.4016
v0.0.391
Package status
Submission, indexing, and post-publish processing milestones for this release.
Submitted
May 15, 08:08 PM
Indexed
May 15, 08:08 PM
Searchable
May 15, 08:08 PM
Docs ready
May 15, 08:09 PM
Completed
Pending
Dependencies
Dependencies declared for this release.
No dependencies Expand

No dependencies declared for this release.

Dependents
Packages that currently depend on kernel.
Show 6 dependents Expand
Recent activity
Latest publication, indexing, and post-publish pipeline events recorded for this package.
Open full activity
Show 12 recent events Expand
  • Blocked
    kernel 0.0.43 attempt 3 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:39:48 PM
    Event
    Blocked
    Package
    kernel
    Version
    0.0.43
    Facts
    attempt 3 artifact 8b91b1fb9db1
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "status": "blocked",
  "attempt_count": 3,
  "error": "error: Unknown argument: kernel"
}
  • Build failed
    kernel 0.0.43 build · exit 1 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:39:46 PM
    Event
    Build failed
    Package
    kernel
    Version
    0.0.43
    Summary
    error: Unknown argument: kernel
    Facts
    build exit 1 artifact 8b91b1fb9db1
    Artifacts
    Result key
    pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/result.json
    Logs key
    pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/build.log
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "run_kind": "build",
  "result_key": "pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/result.json",
  "logs_key": "pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/build.log",
  "environment_probe": {
    "success": true,
    "exit_code": 0,
    "stdout": "glibc=glibc 2.39\nriot=riot 0.0.43 (build 2a3a2071a5f0)\nPRETTY_NAME=\"Ubuntu 24.04.4 LTS\"\nNAME=\"Ubuntu\"\nVERSION_ID=\"24.04\"\nVERSION=\"24.04.4 LTS (Noble Numbat)\"\nVERSION_CODENAME=noble\nID=ubuntu\nID_LIKE=debian\nHOME_URL=\"https://www.ubuntu.com/\"\nSUPPORT_URL=\"https://help.ubuntu.com/\"\nBUG_REPORT_URL=\"https://bugs.launchpad.net/ubuntu/\"\nPRIVACY_POLICY_URL=\"https://www.ubuntu.com/legal/terms-and-policies/privacy-policy\"\nUBUNTU_CODENAME=noble\nLOGO=ubuntu-logo",
    "stderr": "",
    "duration_ms": 161,
    "command": [
      "sh",
      "-lc",
      "printf 'glibc=%s\\n' \"$(getconf GNU_LIBC_VERSION 2>/dev/null || echo unknown)\" && printf 'riot=%s\\n' \"$(/root/.riot/bin/riot version 2>/dev/null || echo unavailable)\" && cat /etc/os-release"
    ],
    "json_events": [],
    "non_json_stdout_lines": [
      "glibc=glibc 2.39",
      "riot=riot 0.0.43 (build 2a3a2071a5f0)",
      "PRETTY_NAME=\"Ubuntu 24.04.4 LTS\"",
      "NAME=\"Ubuntu\"",
      "VERSION_ID=\"24.04\"",
      "VERSION=\"24.04.4 LTS (Noble Numbat)\"",
      "VERSION_CODENAME=noble",
      "ID=ubuntu",
      "ID_LIKE=debian",
      "HOME_URL=\"https://www.ubuntu.com/\"",
      "SUPPORT_URL=\"https://help.ubuntu.com/\"",
      "BUG_REPORT_URL=\"https://bugs.launchpad.net/ubuntu/\"",
      "PRIVACY_POLICY_URL=\"https://www.ubuntu.com/legal/terms-and-policies/privacy-policy\"",
      "UBUNTU_CODENAME=noble",
      "LOGO=ubuntu-logo"
    ]
  },
  "exit_code": 1,
  "json_event_count": 0,
  "non_json_stdout_count": 1,
  "failure_summary": "error: Unknown argument: kernel",
  "stdout_excerpt": "error: Unknown argument: kernel"
}
  • Processing
    kernel 0.0.43 attempt 3 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:39:41 PM
    Event
    Processing
    Package
    kernel
    Version
    0.0.43
    Facts
    attempt 3 artifact 8b91b1fb9db1
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "status": "processing",
  "attempt_count": 3
}
  • Requeued
    kernel 0.0.43 attempt 2 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:34:15 PM
    Event
    Requeued
    Package
    kernel
    Version
    0.0.43
    Facts
    attempt 2 artifact 8b91b1fb9db1
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "status": "pending",
  "attempt_count": 2,
  "next_attempt_at": "2026-05-15T20:39:15.520Z",
  "error": "error: Unknown argument: kernel"
}
  • Build failed
    kernel 0.0.43 build · exit 1 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:34:13 PM
    Event
    Build failed
    Package
    kernel
    Version
    0.0.43
    Summary
    error: Unknown argument: kernel
    Facts
    build exit 1 artifact 8b91b1fb9db1
    Artifacts
    Result key
    pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/result.json
    Logs key
    pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/build.log
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "run_kind": "build",
  "result_key": "pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/result.json",
  "logs_key": "pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/build.log",
  "environment_probe": {
    "success": true,
    "exit_code": 0,
    "stdout": "glibc=glibc 2.39\nriot=riot 0.0.43 (build 2a3a2071a5f0)\nPRETTY_NAME=\"Ubuntu 24.04.4 LTS\"\nNAME=\"Ubuntu\"\nVERSION_ID=\"24.04\"\nVERSION=\"24.04.4 LTS (Noble Numbat)\"\nVERSION_CODENAME=noble\nID=ubuntu\nID_LIKE=debian\nHOME_URL=\"https://www.ubuntu.com/\"\nSUPPORT_URL=\"https://help.ubuntu.com/\"\nBUG_REPORT_URL=\"https://bugs.launchpad.net/ubuntu/\"\nPRIVACY_POLICY_URL=\"https://www.ubuntu.com/legal/terms-and-policies/privacy-policy\"\nUBUNTU_CODENAME=noble\nLOGO=ubuntu-logo",
    "stderr": "",
    "duration_ms": 62,
    "command": [
      "sh",
      "-lc",
      "printf 'glibc=%s\\n' \"$(getconf GNU_LIBC_VERSION 2>/dev/null || echo unknown)\" && printf 'riot=%s\\n' \"$(/root/.riot/bin/riot version 2>/dev/null || echo unavailable)\" && cat /etc/os-release"
    ],
    "json_events": [],
    "non_json_stdout_lines": [
      "glibc=glibc 2.39",
      "riot=riot 0.0.43 (build 2a3a2071a5f0)",
      "PRETTY_NAME=\"Ubuntu 24.04.4 LTS\"",
      "NAME=\"Ubuntu\"",
      "VERSION_ID=\"24.04\"",
      "VERSION=\"24.04.4 LTS (Noble Numbat)\"",
      "VERSION_CODENAME=noble",
      "ID=ubuntu",
      "ID_LIKE=debian",
      "HOME_URL=\"https://www.ubuntu.com/\"",
      "SUPPORT_URL=\"https://help.ubuntu.com/\"",
      "BUG_REPORT_URL=\"https://bugs.launchpad.net/ubuntu/\"",
      "PRIVACY_POLICY_URL=\"https://www.ubuntu.com/legal/terms-and-policies/privacy-policy\"",
      "UBUNTU_CODENAME=noble",
      "LOGO=ubuntu-logo"
    ]
  },
  "exit_code": 1,
  "json_event_count": 0,
  "non_json_stdout_count": 1,
  "failure_summary": "error: Unknown argument: kernel",
  "stdout_excerpt": "error: Unknown argument: kernel"
}
  • Processing
    kernel 0.0.43 attempt 2 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:34:08 PM
    Event
    Processing
    Package
    kernel
    Version
    0.0.43
    Facts
    attempt 2 artifact 8b91b1fb9db1
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "status": "processing",
  "attempt_count": 2
}
  • Requeued
    kernel 0.0.43 attempt 1 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:11:10 PM
    Event
    Requeued
    Package
    kernel
    Version
    0.0.43
    Facts
    attempt 1 artifact 8b91b1fb9db1
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "status": "pending",
  "attempt_count": 1,
  "next_attempt_at": "2026-05-15T20:16:10.369Z",
  "error": "error: Unknown argument: kernel"
}
  • Docs ready
    kernel 0.0.43 docs · 2 json · doc.package_generation_completed · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:09:30 PM
    Event
    Docs ready
    Package
    kernel
    Version
    0.0.43
    Facts
    docs 2 json doc.package_generation_completed artifact 8b91b1fb9db1
    Artifacts
    Result key
    pipelines/docs/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/result.json
    Logs key
    pipelines/docs/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/command.log
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "run_kind": "docs",
  "output_prefix": "docs/kernel/0.0.43/",
  "public_docs_url": "https://docs.pkgs.ml/p/kernel/0.0.43/",
  "result_key": "pipelines/docs/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/result.json",
  "logs_key": "pipelines/docs/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/command.log",
  "json_event_count": 2,
  "non_json_stdout_count": 0,
  "last_json_event_type": "doc.package_generation_completed"
}
  • Build failed
    kernel 0.0.43 build · exit 1 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:09:28 PM
    Event
    Build failed
    Package
    kernel
    Version
    0.0.43
    Summary
    error: Unknown argument: kernel
    Facts
    build exit 1 artifact 8b91b1fb9db1
    Artifacts
    Result key
    pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/result.json
    Logs key
    pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/build.log
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "run_kind": "build",
  "result_key": "pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/result.json",
  "logs_key": "pipelines/builds/kernel/0.0.43/8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e/build.log",
  "environment_probe": {
    "success": true,
    "exit_code": 0,
    "stdout": "glibc=glibc 2.39\nriot=riot 0.0.42 (build 383575aeec54)\nPRETTY_NAME=\"Ubuntu 24.04.4 LTS\"\nNAME=\"Ubuntu\"\nVERSION_ID=\"24.04\"\nVERSION=\"24.04.4 LTS (Noble Numbat)\"\nVERSION_CODENAME=noble\nID=ubuntu\nID_LIKE=debian\nHOME_URL=\"https://www.ubuntu.com/\"\nSUPPORT_URL=\"https://help.ubuntu.com/\"\nBUG_REPORT_URL=\"https://bugs.launchpad.net/ubuntu/\"\nPRIVACY_POLICY_URL=\"https://www.ubuntu.com/legal/terms-and-policies/privacy-policy\"\nUBUNTU_CODENAME=noble\nLOGO=ubuntu-logo",
    "stderr": "",
    "duration_ms": 57,
    "command": [
      "sh",
      "-lc",
      "printf 'glibc=%s\\n' \"$(getconf GNU_LIBC_VERSION 2>/dev/null || echo unknown)\" && printf 'riot=%s\\n' \"$(/root/.riot/bin/riot version 2>/dev/null || echo unavailable)\" && cat /etc/os-release"
    ],
    "json_events": [],
    "non_json_stdout_lines": [
      "glibc=glibc 2.39",
      "riot=riot 0.0.42 (build 383575aeec54)",
      "PRETTY_NAME=\"Ubuntu 24.04.4 LTS\"",
      "NAME=\"Ubuntu\"",
      "VERSION_ID=\"24.04\"",
      "VERSION=\"24.04.4 LTS (Noble Numbat)\"",
      "VERSION_CODENAME=noble",
      "ID=ubuntu",
      "ID_LIKE=debian",
      "HOME_URL=\"https://www.ubuntu.com/\"",
      "SUPPORT_URL=\"https://help.ubuntu.com/\"",
      "BUG_REPORT_URL=\"https://bugs.launchpad.net/ubuntu/\"",
      "PRIVACY_POLICY_URL=\"https://www.ubuntu.com/legal/terms-and-policies/privacy-policy\"",
      "UBUNTU_CODENAME=noble",
      "LOGO=ubuntu-logo"
    ]
  },
  "exit_code": 1,
  "json_event_count": 0,
  "non_json_stdout_count": 1,
  "failure_summary": "error: Unknown argument: kernel",
  "stdout_excerpt": "error: Unknown argument: kernel"
}
  • Processing
    kernel 0.0.43 attempt 1 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:09:11 PM
    Event
    Processing
    Package
    kernel
    Version
    0.0.43
    Facts
    attempt 1 artifact 8b91b1fb9db1
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "status": "processing",
  "attempt_count": 1
}
  • Queued
    kernel 0.0.43 artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:09:06 PM
    Event
    Queued
    Package
    kernel
    Version
    0.0.43
    Facts
    artifact 8b91b1fb9db1
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "status": "pending"
}
  • Indexed
    kernel 0.0.43 latest 0.0.43 · artifact 8b91b1fb9db1
    Details
    When
    May 15, 2026, 08:08:59 PM
    Event
    Indexed
    Package
    kernel
    Version
    0.0.43
    Facts
    latest 0.0.43 artifact 8b91b1fb9db1
    Payload
    {
  "artifact_sha256": "8b91b1fb9db10cbc312239435ec5e1d57c4166a3c89c803670b44a06a4476a5e",
  "latest": "0.0.43",
  "package_index_key": "index/v1/ke/rn/kernel.json",
  "package_index_url": "https://cdn.pkgs.ml/index/v1/ke/rn/kernel.json",
  "changed": true
}