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_core.h

@@ -0,0 +1,70 @@
+#ifndef VMSIG_CORE_H
+#define VMSIG_CORE_H
+#include "vmsig_event.h"
+#include "vmsig_ctx.h"
+#include "vmsig_adapter.h"
+#include "vmsig_control.h"
+
+/* vmsig_core.h — non-blocking epoll core. It knows a single vocabulary: "here is
+ * an fd — call the neutral handler on readiness; the handler produces/consumes
+ * neutral events". All neighbor mechanisms are just different ways to spawn an
+ * fd. The core structurally cannot name a neighbor's type: neighbor headers are
+ * visible only from the adapter TUs. */
+
+typedef struct vmsig_core vmsig_core;
+
+/* Create the core over a transfer context (the core does NOT own ctx; ctx's
+ * lifetime must cover the core). NULL on error. */
+vmsig_core* vmsig_core_new(vmsig_ctx* ctx);
+
+/* Stop, detach all adapters/control, free. Safe on NULL. */
+void        vmsig_core_free(vmsig_core* c);
+
+/* ===== Audit (observability of admissions/denials) ===== */
+typedef enum {
+    VMSIG_AUDIT_ADMIT         = 0,   /* poller admitted (socket accept)          */
+    VMSIG_AUDIT_REJECT        = 1,   /* poller rejected at accept (empty grant)  */
+    VMSIG_AUDIT_DOWN_DENIED   = 2,   /* DOWN command denied by grant/cap         */
+    /* --- lease arbitration --- */
+    VMSIG_AUDIT_LEASE_GRANTED = 3,   /* lease granted/preempted                  */
+    VMSIG_AUDIT_LEASE_DENIED  = 4,   /* ACQUIRE denied OR destructive dropped by lease gate */
+    VMSIG_AUDIT_LEASE_REVOKED = 5,   /* lease revoked by preemption              */
+    VMSIG_AUDIT_LEASE_RECLAIMED = 6, /* lease reclaimed on owner death (reclaim) */
+    VMSIG_AUDIT_MEMCTX_GRANTED  = 7  /* address-space context granted/replayed to holder */
+} vmsig_audit_kind;
+
+typedef struct {
+    vmsig_audit_kind kind;
+    uint32_t principal;   /* uid/token (grant.principal or peer uid)         */
+    uint32_t endpoint;
+    uint32_t cmd;         /* vmsig_kind for DOWN_DENIED                      */
+    uint32_t detail;      /* extra (e.g. peer pid)                          */
+} vmsig_audit;
+
+/* Set the audit callback (NULL = off). Called on the loop thread. */
+void        vmsig_core_set_audit(vmsig_core* c,
+                                 void (*cb)(void* ud, const vmsig_audit* a), void* ud);
+
+/* Set the lease arbitration policy (NULL => default: contender.arb_prio >
+ * incumbent.arb_prio ? PREEMPT : DENY). Called on the loop thread. */
+void        vmsig_core_set_arb_policy(vmsig_core* c, vmsig_arb_policy cb, void* ud);
+
+/* Register an adapter for VM `endpoint`: open(cfg,endpoint) -> attach(...),
+ * enroll each yielded fd into epoll and into the dispatch table fd->(adapter,cookie).
+ * Returns the adapter id (>=0) or -1. */
+int  vmsig_core_add_adapter(vmsig_core* c, const vmsig_adapter_ops* ops,
+                            const void* cfg, uint32_t endpoint);
+
+/* Attach a control endpoint (in-process or socket) with a GRANT (capability set).
+ * grant == NULL => default-deny (poller inert). The core sees only the neutral
+ * vtable + grant + (opt.) fd. Returns the control id (>=0) or -1. */
+int  vmsig_core_add_control(vmsig_core* c, const vmsig_control_ops* ops, void* ctl,
+                            const vmsig_grant* grant);
+
+/* Spin the loop until a stop is requested. 0 — clean, -1 — fatal. */
+int  vmsig_core_run(vmsig_core* c);
+
+/* Asynchronous, signal-safe stop request: writes the wakeup eventfd. */
+void vmsig_core_stop(vmsig_core* c);
+
+#endif /* VMSIG_CORE_H */