Add trusted in-process dynamic modules

.github/workflows/ci.yml

@@ -9,11 +9,15 @@ env:
   CARGO_TERM_COLOR: always
   RUSTFLAGS: -D warnings
 
+permissions: {}
+
 jobs:
   check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: rustfmt, clippy
@@ -34,14 +38,17 @@ jobs:
       - name: Slim build
         run: cargo check --locked --no-default-features
 
+      - name: Module loader without sockets
+        run: cargo check --locked --no-default-features --features modules
+
       - name: Docs
         run: cargo doc --locked --all-features --no-deps
         env:
           RUSTDOCFLAGS: -D warnings
 
   # The bus is meant to be embeddable on every platform OpenHuman ships on. The
-  # Unix transport is Unix-only by construction, so Windows builds the slim
-  # configuration until the named-pipe backend lands (ROADMAP.md, M6).
+  # socket adapter remains Unix-only, while the in-process module transport
+  # and dynamic loader are portable and run on both non-Linux targets.
   portability:
     strategy:
       fail-fast: false
@@ -50,9 +57,81 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
       - name: Build
         run: cargo check --locked --no-default-features --features macros
       - name: Test
         run: cargo test --locked --no-default-features --features macros
+      - name: Test modules without sockets
+        run: cargo test --locked --no-default-features --features modules,macros
+
+  modules:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Build example module
+        run: cargo build --locked --example module_clock --example module_clock_two --example module_wrong_target --no-default-features --features modules,macros
+      - name: Exercise the real loader (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          set -euo pipefail
+          module=$(find target/debug/examples -maxdepth 1 -type f \( -name 'libmodule_clock.so' -o -name 'libmodule_clock.dylib' \) -print -quit)
+          module_two=$(find target/debug/examples -maxdepth 1 -type f \( -name 'libmodule_clock_two.so' -o -name 'libmodule_clock_two.dylib' \) -print -quit)
+          wrong_target=$(find target/debug/examples -maxdepth 1 -type f \( -name 'libmodule_wrong_target.so' -o -name 'libmodule_wrong_target.dylib' \) -print -quit)
+          for artifact in "$module" "$module_two" "$wrong_target"; do
+            if [ -z "$artifact" ] || [ ! -f "$artifact" ]; then
+              echo "a module example artifact is missing; the loader tests would not exercise it" >&2
+              exit 1
+            fi
+          done
+          TINYBUS_TEST_MODULE="$PWD/$module" TINYBUS_TEST_MODULE_TWO="$PWD/$module_two" TINYBUS_TEST_WRONG_TARGET="$PWD/$wrong_target" cargo test --locked --no-default-features --features modules,macros -- --ignored
+      - name: Exercise the real loader (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $private = Join-Path $PWD target/private-module-tests
+          New-Item -ItemType Directory -Force $private | Out-Null
+          $identity = [System.Security.Principal.WindowsIdentity]::GetCurrent()
+          $acl = [System.Security.AccessControl.DirectorySecurity]::new()
+          $acl.SetOwner($identity.User)
+          $acl.SetAccessRuleProtection($true, $false)
+          $inherit = [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+          $rule = [System.Security.AccessControl.FileSystemAccessRule]::new(
+            $identity.User,
+            [System.Security.AccessControl.FileSystemRights]::FullControl,
+            $inherit,
+            [System.Security.AccessControl.PropagationFlags]::None,
+            [System.Security.AccessControl.AccessControlType]::Allow
+          )
+          $acl.AddAccessRule($rule)
+          Set-Acl -LiteralPath $private -AclObject $acl
+          Copy-Item target/debug/examples/module_clock.dll $private
+          Copy-Item target/debug/examples/module_clock_two.dll $private
+          Copy-Item target/debug/examples/module_wrong_target.dll $private
+          $mixed = Join-Path $private mixed
+          New-Item -ItemType Directory -Force $mixed | Out-Null
+          Set-Acl -LiteralPath $mixed -AclObject $acl
+          Copy-Item target/debug/examples/module_clock.dll $mixed
+          Copy-Item target/debug/examples/module_wrong_target.dll $mixed
+          $module = (Get-ChildItem "$private/module_clock.dll" | Select-Object -First 1).FullName
+          $moduleTwo = (Get-ChildItem "$private/module_clock_two.dll" | Select-Object -First 1).FullName
+          $wrongTarget = (Get-ChildItem "$private/module_wrong_target.dll" | Select-Object -First 1).FullName
+          $env:TEMP = $private
+          $env:TMP = $private
+          $env:TINYBUS_TEST_MODULE = $module
+          $env:TINYBUS_TEST_MODULE_TWO = $moduleTwo
+          $env:TINYBUS_TEST_WRONG_TARGET = $wrongTarget
+          $env:TINYBUS_TEST_MODULE_DIRECTORY = $mixed
+          cargo test --locked --no-default-features --features modules,macros -- --ignored

AGENTS.md

@@ -107,3 +107,10 @@ discussion in the pull request:
   best-effort signal delivery, and an accept loop that survives a bad client are
   all this invariant. Any change that lets one peer's slowness reach another's
   latency is a bug, not a tuning question.
+- **In-process modules are inside the trust boundary, not outside it.** The
+  misbehaving-peer invariant applies to peers reached across a real transport
+  boundary. A module loaded with `dlopen` shares the host address space and is
+  trusted exactly as much as the host's own code. Bounded queues, deadlines and
+  caught panics bound misbehaviour; they cannot contain a segfault, abort, heap
+  corruption, OOM, or deliberate memory access. An integration whose crash or
+  compromise must not reach the kernel belongs in a separate process.

Cargo.toml

@@ -1,13 +1,12 @@
 [workspace]
-# Two crates, and there is a reason it is not one. `tinybus-macros` is a
+# Three crates, and there is a reason they are not one. `tinybus-macros` is a
 # proc-macro crate, which means it compiles for the *host* even when the bus
 # itself is cross-compiled; keeping it separate is the only way to have
 # `#[interface]` without forcing that split on every downstream target.
-# Integrations themselves are never workspace members — the whole point is that
-# an integration is a separate process (or a separate crate in its own repo)
-# that speaks the wire protocol. Adding an integration here would re-create the
-# dependency blob we are trying to delete from the kernel.
-members = ["crates/tinybus", "crates/tinybus-macros"]
+# `tinybus-module` is the module-side half of the C ABI. It is versioned here in
+# lockstep with the host ABI so the two definitions cannot drift. Integrations
+# themselves remain separate repositories and are never workspace members.
+members = ["crates/tinybus", "crates/tinybus-macros", "crates/tinybus-module"]
 resolver = "3"
 
 [workspace.package]
@@ -17,8 +16,10 @@ license = "GPL-3.0-only"
 repository = "https://github.com/tinyhumansai/tinybus"
 
 [workspace.dependencies]
-tinybus = { path = "crates/tinybus", version = "0.1.0" }
+tinybus = { path = "crates/tinybus", version = "0.1.0", default-features = false }
 tinybus-macros = { path = "crates/tinybus-macros", version = "0.1.0" }
+tinybus-module = { path = "crates/tinybus-module", version = "0.1.0" }
+tokio = { version = "1", features = ["rt-multi-thread", "sync", "time"] }
 
 async-trait = "0.1"
 serde = { version = "1", features = ["derive"] }

README.md

@@ -90,13 +90,19 @@ crates/tinybus/          the bus: protocol, broker, connection, proxy
   src/name/              validated addresses (bus name, path, interface, member)
   src/ports/             the two seams: Transport and Listener
   src/transport/         in-memory (always) and Unix socket (feature `uds`)
+  src/module/            stable module ABI and optional dynamic loader
+  src/events/            bounded in-process domain event fan-out
+  src/global.rs          process-wide one-time bus installation
+  src/native.rs          typed in-process request registry
+  src/version.rs         peer and interface compatibility declarations
   src/router.rs          the routing table and match rules
   src/broker.rs          the daemon
   src/connection.rs      a peer's link: calls out, dispatch in
   src/proxy.rs           the client handle — the kernel's whole API surface
   src/service/           the Interface trait and the object tree
   src/bin/tinybus.rs     the CLI
 crates/tinybus-macros/   #[interface]
+crates/tinybus-module/   module-side runtime and export macro
 docs/modules/            one document per module
 ```
 
@@ -107,17 +113,20 @@ docs/modules/            one document per module
 | `uds` | yes | Unix-socket transport — the production one |
 | `macros` | yes | `#[tinybus::interface]` |
 | `cli` | yes | the `tinybus` binary |
+| `modules` | no | trusted in-process `cdylib` discovery and loading |
 
 `--no-default-features` leaves the protocol, the router, the broker and the
 in-memory transport: no sockets, no proc-macro build step, no CLI. That is the
 configuration a slim kernel build embeds.
 
 ## Status
 
-Milestone 1. The core protocol, broker, connection, proxy, macro, Unix
-transport and CLI are implemented and tested. Service activation, file-descriptor
-passing, per-peer authorisation policy and the Windows named-pipe backend are
-not — see `ROADMAP.md`.
+The core protocol, broker, connection, proxy, macro, Unix transport and CLI are
+implemented and tested. Trusted in-process modules support lazy activation
+behind the non-default `modules` feature; read the module trust-boundary notes
+before enabling it. External service-process or bus-driven activation remains
+unimplemented. File-descriptor passing, per-peer authorisation policy and the
+Windows named-pipe backend are also not implemented — see `ROADMAP.md`.
 
 ## Licence
 

ROADMAP.md

@@ -47,21 +47,23 @@ Deliberately **not** on this list: `tinyagents`, `tinycortex`, `tinyflows`,
 crates. Moving them behind a bus would add latency and a serialisation boundary
 to the hot path and remove nothing.
 
-## M3 — activation
+## M3 — trusted in-process modules
 
-Right now a service must already be running. Activation makes the broker start
-one on demand: a call to a name nobody owns consults a service file, launches
-the process, waits for it to claim the name, and then delivers the call.
+OpenHuman may embed the broker and load selected integrations as `cdylib`
+modules. Each module is an ordinary peer connected at the `Transport` seam,
+with its own runtime and bounded queues. The ABI gate rejects incompatible
+artifacts before calling their initialization entrypoint.
 
-This is what turns "the integration is not installed" into a non-error for the
-common case, and it is what makes lazily-paid dependencies real — an
-integration that is never used is a process that never starts.
+This is deployment convenience, not process isolation. Loading a library runs
+arbitrary code with the host's privileges and puts it inside the host's memory
+and crash boundary. Integrations that hold especially sensitive material or
+need fault containment remain separate processes.
 
-- [ ] Service files: name, exec line, environment, timeout
-- [ ] Launch, wait for `RequestName`, deliver the queued call
-- [ ] Refuse to relaunch a service that is crash-looping, with a clear error
-      rather than a fork bomb
-- [ ] `tinybus list --activatable`
+- [x] Versioned, C-shaped descriptor and manifest ABI
+- [x] Module-side runtime and export macro
+- [x] Host transport bridge, admission gate, dependency ordering and loader
+- [x] Linux, macOS and Windows loader implementations
+- [x] Bus and CLI module inspection/control surface
 
 ## M4 — the security boundary
 
@@ -96,6 +98,14 @@ sender is responsible for the file's lifetime.
 - [ ] A TypeScript client, because some integrations genuinely want the Node
       ecosystem and shelling out to it is worse than speaking the protocol
 
+## M7 — external service activation
+
+The trusted-module loader is not a replacement for activating isolated service
+processes. A later milestone must define service-file discovery, process
+launching, delivery of calls queued during startup, crash-loop prevention, and
+how activatable names appear in inspection APIs before bus-driven activation is
+safe to claim.
+
 ## Not planned
 
 - **A network transport.** The bus is local by construction, and every

crates/tinybus-module/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "tinybus-module"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Module-side runtime and export macro for trusted tinybus cdylibs."
+
+[dependencies]
+async-trait.workspace = true
+serde_json.workspace = true
+serde.workspace = true
+tinybus.workspace = true
+tokio.workspace = true
+tracing.workspace = true