Primal Interactions — IPC Architecture

The Core Rule

No compile-time coupling. All coordination via JSON-RPC 2.0 over Unix domain sockets. A primal does not import another primal’s code. A primal does not link against another primal’s library. A primal communicates by sending JSON messages through a socket.

This rule is not a preference. It is the constraint that makes independent evolution possible — any primal can upgrade without recompiling any other primal.

Transport Stack

Socket Paths

$XDG_RUNTIME_DIR/biomeos/{primal}.sock

Each primal has its own socket. 🎵🐦 Songbird maintains the registry of active sockets and their capabilities.

Discovery Hierarchy

How does a primal find another primal? Four-tier fallback:

A primal attempting to discover 🐻🐕 BearDog checks tier 1 first. If unset, it scans tier 2. The hierarchy ensures that primals work in development, containerized, and production environments without configuration changes.

The 🎵🐦 Songbird Hub

🎵🐦 Songbird is the O(n) discovery hub. Without it, each primal would need to discover every other primal independently — O(n²) connections. With 🎵🐦 Songbird:

All primals register with Songbird (n registrations)
Any primal queries Songbird for capabilities (1 lookup)
Songbird routes to the correct socket (1 connection)

Total connections: O(n) instead of O(n²).

The 🌿🖥️ biomeOS Neural API Semantic Layer

Above the raw JSON-RPC transport sits the Neural API semantic layer. Instead of calling a specific primal’s method directly, a product or spring calls:

{"method": "capability.call", "params": {"capability": "crypto.sign", "data": "..."}}

🌿🖥️ biomeOS resolves crypto.sign to beardog.crypto.sign and routes the call. This means:

• Products do not know which primal implements a capability — they know what they need, not who provides it
• Primals can be replaced — if crypto.sign is implemented by a different primal in the future, the product does not change
• Capabilities compose — compute.matrix_mul might dispatch to 🐟⚡ barraCuda (GPU) or CPU fallback depending on hardware

Method Registration

Every primal registers its methods with 🎵🐦 Songbird at startup:

{
  "method": "ipc.register",
  "params": {
    "primal": "beardog",
    "methods": ["crypto.sign", "crypto.verify", "secrets.store", ...],
    "socket": "/run/biomeos/beardog.sock"
  }
}

The registration includes the full method list and the socket path. 🎵🐦 Songbird builds a capability routing table from all registrations.

Interaction Patterns

Request-Response (Standard)

Most primal interactions are request-response:

Product -> biomeOS: capability.call("crypto.sign", data)
biomeOS -> beardog: crypto.sign(data)
beardog -> biomeOS: {result: signature}
biomeOS -> Product: {result: signature}

Fire-and-Forget (Telemetry)

Health probes and telemetry use fire-and-forget:

biomeOS -> beardog: health.ping()
beardog -> biomeOS: {status: "healthy", uptime: 3600}

Event Stream (Future)

For continuous coordination (game sessions, live monitoring), event streams over persistent connections.

The No-Coupling Rule in Practice

The IPC architecture is not a convenience layer. It is the constraint that makes the ecosystem possible — 14 independent programs, each with its own release cycle, communicating through a standard protocol, discovered at runtime, composed by 🌿🖥️ biomeOS into whatever the science requires.