# RFC: Omega Mesh Inter-Process Communication (OM-IPC) v1.0
## 1. Abstract

The OM-IPC protocol defines a standardized, zero-trust messaging architecture
that allows decoupled entities (Browser Tabs, Web Workers, Mesh OS Daemons,
and external bare-metal Agents) to discover capabilities, execute tasks, and
exchange data. The protocol is agnostic to the transport layer and treats
local inter-tab communication identically to remote WebSocket relay
communication.

## 2. Transport Layers

Nodes must implement at least one of the following transport mechanisms to
participate in the Mesh:

* **Local Mesh (Inter-Tab/Worker):** Utilizes the native HTML5
`BroadcastChannel` API (e.g., `new BroadcastChannel('omega_mesh_bus')`). This
provides zero-latency, secure, same-origin communication between isolated
single-page apps (SPAs) and Mesh OS.
* **Remote Mesh (WebSocket):** Utilizes the `mesh_bridge_tx/rx` daemons to
route OM-IPC envelopes over an authenticated WSS relay to external kernels
(Node.js, mquickjs).

## 3. Standard Message Envelope

All communications across the mesh MUST wrap payloads in this standard JSON
envelope.

```json
{
  "id": "msg_1790610000_abc123",
  "ts": 1790610000123,
  "source": {
    "node": "tab_pdf_generator", 
    "key": "<auth_pubkey_placeholder>"
  },
  "target": "mesh_os_core",     // Specific node ID, or "*" for broadcast
  "action": "VFS_READ_REQUEST", // The intent verb
  "auth_token": "<capability_token_placeholder>", 
  "payload": { ... }            // Action-specific data
}

```

## 4. Protocol Specifications
### 4.1 Node Discovery & Gossiping (`NODE_ANNOUNCE`)

When a participant connects to a transport layer, it MUST broadcast its
identity and capabilities. Other nodes listen to these announcements to build
a dynamic routing table of available services.

**Action:** `NODE_ANNOUNCE` (Target: `*`)
**Payload:**

```json
{
  "capabilities": ["vfs_host", "compute_pdf", "llm_inference"],
  "vfs_namespaces": ["/sys_data", "/home"],
  "status": "idle"
}

```

*Behavior:* Mesh OS hears this and registers the tab/node. If Mesh OS needs a
PDF generated later, it knows exactly which node to target.

### 4.2 VFS Directory Querying (`VFS_QUERY`)

Allows a participant to request the directory tree of another node's Virtual
File System.

**Action:** `VFS_QUERY`
**Payload:**

```json
{
  "path": "/home/docs",
  "recursive": false
}

```

**Response Action:** `VFS_QUERY_RESULT`
**Payload:**

```json
{
  "path": "/home/docs",
  "contents": [
    { "type": "file", "name": "smartjoin.md", "size": 1024 },
    { "type": "directory", "name": "archives", "size": 0 }
  ],
  "error": null
}

```

### 4.3 VFS Data Transfer (`VFS_READ` / `VFS_WRITE`)

*(Adopts the existing pipeline currently utilized by the Mesh Agent)*. Used
for secure file streaming across the boundary.

**Action:** `VFS_READ_REQUEST`
**Payload:** `{ "path": "/home/docs/smartjoin.md" }`

**Response Action:** `VFS_READ_CHUNK`
**Payload:** `{ "path": "/home/docs/smartjoin.md", "chunk": "..." }`
*(Followed by `VFS_READ_COMPLETE` when the stream finishes).*

**Action:** `VFS_WRITE_REQUEST`
**Payload:** `{ "path": "/home/docs/new.md", "data": "..." }`

### 4.4 Task Execution (`TASK_RPC`)

Allows Mesh OS to farm out specialized work to standalone HTML tabs without
bringing their codebase into the OS.

**Action:** `TASK_RPC_REQUEST`
**Payload:**

```json
{
  "task_id": "job_998877",
  "executable": "generate_invoice",
  "args": {
    "customer_id": "CUST-001",
    "amount": 500
  }
}

```

*Behavior:* Tab 2 (a standalone Invoice App) catches this, generates the PDF
locally using its own bundled libraries, saves the file directly to Mesh OS
via a `VFS_WRITE_REQUEST`, and finally sends a `TASK_RPC_RESULT` signaling
completion.

## 5. Security & Authorization (Placeholders)

To ensure the `BroadcastChannel` and Relay aren't abused by malicious or
unauthorized scripts, the OM-IPC protocol dictates two security mechanisms to
be implemented at a later phase:

1. **Authorized Keys Registry:** Mesh OS will maintain a `authorized_keys.json`
 file in its kernel space. The `"source.key"` in the message envelope must
match a known key to access privileged intents (like `VFS_WRITE`).
2. **Capability Tokens:** When a node successfully authenticates, Mesh OS
issues a temporary cryptographic token (`auth_token`). This token scopes
access (e.g., "This tab can read `/home/public` but cannot access
`/sys_data`").