vmsig: a neutral signaling layer between sensors/input and controls

An epoll-driven, neutral transfer-event bus that connects sensors and input
actuators to one or more controls, bidirectionally. It owns the transfer context
and events — delivery order, priority, protocol-level timing, and an
interrupt-driven event model over fd sources (eventfd/timerfd/sockets) — and
stays agnostic to both the sensor/input drivers and the control.

What lives here:
- memctx: a coherent address-space context per endpoint — the guest address-space
  root paired with a pre-opened read-only RAM-region fd, with per-endpoint epoch
  invalidation and retained replay to late subscribers. Perception lives in
  out-of-tree sensor libraries that consume this datum read-only.
- exclusive-ownership leases for destructive resource classes (input, power,
  memory-write).
- write-signaled memory writes (MEMWRITE): an atomic write to guest memory routed
  through the seam under an exclusive lease, never a writable mapping.
- a host-management seam for VM lifecycle/status and a neutral input-injection
  command path.
- multi-VM endpoints; capability-gated, audited control authorization over an
  in-process or unix-socket transport.

Builds against headers only by default (a stub mode that exercises the seam
without a VM); armed builds link the real sensor/input libraries behind flags.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

include/vmsig_socket.h

@@ -0,0 +1,42 @@
+#ifndef VMSIG_SOCKET_H
+#define VMSIG_SOCKET_H
+#include "vmsig_event.h"
+#include "vmsig_control.h"   /* vmsig_grant */
+#include "vmsig_core.h"      /* vmsig_core  */
+
+/* vmsig_socket.h — out-of-process control over a unix socket (human/service poller).
+ * signaling LISTENS; each accepted connection is authenticated (SO_PEERCRED) and,
+ * per policy, receives a grant -> becomes a distinct control behind the same seam. */
+
+/* Wire format: fixed-size, pointer-free — the same contract on the external
+ * poller. Single host (unix socket) => native byte order. Only the event's
+ * inline part is serialized (payload pointers do not go on the wire). */
+#define VMSIG_WIRE_MAGIC   0x47495356u   /* 'VSIG' */
+#define VMSIG_WIRE_VERSION 1u
+typedef struct {
+    uint32_t magic;
+    uint32_t version;
+    uint32_t kind;       /* vmsig_kind   */
+    uint32_t source;     /* vmsig_source */
+    uint32_t dir;        /* vmsig_dir    */
+    uint32_t prio;       /* vmsig_prio   */
+    uint32_t endpoint;
+    uint32_t corr;
+    uint8_t  inln[48];   /* inline event payload */
+} vmsig_wire;
+
+/* Frame <-> event codec (for external clients too). */
+void vmsig_wire_encode(vmsig_wire* w, const vmsig_event* ev);
+int  vmsig_wire_decode(const vmsig_wire* w, vmsig_event* ev);   /* 0 ok, -1 bad magic/ver */
+
+/* Admission policy: given the authenticated peer (SO_PEERCRED), return a grant.
+ * An empty grant (cap_mask==0 || endpoint_mask==0) => connection is rejected. */
+typedef vmsig_grant (*vmsig_socket_policy)(uint32_t uid, uint32_t pid, void* ud);
+
+/* Bring up a unix-socket control listener on `path` (prefix '@' => abstract socket).
+ * Driven by the epoll core: accept -> SO_PEERCRED -> policy -> grant -> per-conn
+ * control. Returns 0/-1. */
+int vmsig_socket_attach(vmsig_core* core, const char* path,
+                        vmsig_socket_policy policy, void* ud);
+
+#endif /* VMSIG_SOCKET_H */