feat(wit): define resident actor protocol

Add the versioned wasmeld:resident@0.1.0 event/effect contract for timers, streams, datagrams, messages, extension sources, and shutdown. Add a resident-probe Component with locked service and resident WIT dependencies so the ABI can be built, packed, and exercised independently.
2026-07-30 07:40:02 +08:00
parent b304b038a4
commit 949b8d6cdb
8 changed files with 251 additions and 0 deletions
@@ -0,0 +1,123 @@
+package wasmeld:resident@0.1.0;
+
+/// Event/effect ABI for Components that remain active without monopolizing
+/// their Actor thread. The Host owns timers, subscriptions, sockets, streams,
+/// and all operating-system handles. A Component handles one bounded event and
+/// returns effects before control goes back to the Runtime.
+interface actor {
+  type resource-id = u64;
+
+  record timer-fired {
+    timer-id: resource-id,
+    scheduled-at-ns: u64,
+  }
+
+  record stream-opened {
+    endpoint-id: resource-id,
+    stream-id: resource-id,
+    peer: option<string>,
+  }
+
+  record stream-chunk {
+    stream-id: resource-id,
+    bytes: list<u8>,
+  }
+
+  enum close-reason {
+    peer-closed,
+    host-closed,
+    idle-timeout,
+    protocol-error,
+    transport-error,
+  }
+
+  record stream-closed {
+    stream-id: resource-id,
+    reason: close-reason,
+  }
+
+  record datagram {
+    endpoint-id: resource-id,
+    peer: string,
+    bytes: list<u8>,
+  }
+
+  record message {
+    subscription-id: resource-id,
+    message-id: u64,
+    bytes: list<u8>,
+  }
+
+  /// Escape hatch for Host-owned event sources such as filesystem watchers,
+  /// serial devices, process signals, or platform-specific buses. `kind` and
+  /// `payload` are interpreted by the separately versioned Host capability
+  /// that created `source-id`.
+  record source-event {
+    source-id: resource-id,
+    kind: string,
+    payload: list<u8>,
+  }
+
+  variant event {
+    timer(timer-fired),
+    stream-opened(stream-opened),
+    stream-data(stream-chunk),
+    stream-writable(resource-id),
+    stream-half-closed(resource-id),
+    stream-closed(stream-closed),
+    datagram(datagram),
+    message(message),
+    source(source-event),
+    shutdown,
+  }
+
+  record stream-write {
+    stream-id: resource-id,
+    bytes: list<u8>,
+  }
+
+  record datagram-send {
+    endpoint-id: resource-id,
+    peer: string,
+    bytes: list<u8>,
+  }
+
+  record timer-arm {
+    timer-id: resource-id,
+    delay-ms: u64,
+    interval-ms: option<u64>,
+  }
+
+  record message-ack {
+    subscription-id: resource-id,
+    message-id: u64,
+  }
+
+  record source-command {
+    source-id: resource-id,
+    command: string,
+    payload: list<u8>,
+  }
+
+  variant effect {
+    write-stream(stream-write),
+    close-stream(resource-id),
+    pause-stream(resource-id),
+    resume-stream(resource-id),
+    send-datagram(datagram-send),
+    arm-timer(timer-arm),
+    cancel-timer(resource-id),
+    acknowledge-message(message-ack),
+    source-command(source-command),
+  }
+
+  variant resident-error {
+    event-failed(string),
+  }
+
+  handle-event: func(input: event) -> result<list<effect>, resident-error>;
+}
+
+world resident-component {
+  export actor;
+}