feat(sdk): Context::emit for WIT 1.1 host.emit-event (T1)
Some checks failed
CI / Linux x86_64 (Forgejo) (push) Failing after 1s

Brings the module SDK to WIT 1.1 in lockstep with the platform and
exposes the new host.emit-event as an ergonomic ctx.emit(name,
payload). Modules emit ephemeral progress/stream events (progress,
token streaming) delivered live to a following client and never
persisted.

- wit/world.wit → 1.1.0 (host.emit-event + use types.{payload}).
- host.rs: an emit hook (thread-local fn pointer; guest is
  single-threaded). The #[fai_module] expansion installs a closure
  reaching the real WIT emit-event import at the start of each
  invocation; Context::emit calls through it. Outside a hub (unit
  tests) it is a silent no-op.
- examples/progress: reference module emitting progress + token events;
  builds clean for wasm32-wasip2, proving the ergonomics end-to-end.

The SDK keeps shielding module authors: emit is the whole surface, no
wit_bindgen in sight.

Signed-off-by: flemming-it <sf@flemming.it>
This commit is contained in:
flemming-it 2026-07-05 19:22:53 +02:00
parent 98e98e9371
commit f32dc820b9
9 changed files with 568 additions and 5 deletions

View file

@ -2,7 +2,7 @@
// FROZEN. Wire contract between hub and modules.
// =============================================================
//
// This file is the stable wire contract between the F∆I Hub
// This file is the stable wire contract between the Ch∆In Hub
// and any module compiled against it. It is **frozen at v1.0**.
//
// Frozen means:
@ -20,11 +20,11 @@
// See `crates/fai_runtime/tests/wit_freeze.rs`.
//
// Module authors do NOT depend on this file directly. They
// use `fai-module-sdk`, which wraps these bindings behind a
// use `chain-module-sdk`, which wraps these bindings behind a
// stable, ergonomic surface. That is what protects modules
// from any future evolution of this contract.
package chain:platform@1.0.0;
package chain:platform@1.1.0;
/// Types that flow between the host (hub) and modules.
interface types {
@ -74,8 +74,19 @@ interface types {
/// The host-provided interface that modules can import to talk back.
interface host {
use types.{payload};
/// Log a structured message. Level is "trace", "debug", "info", "warn", "error".
log: func(level: string, message: string);
/// Emit an ephemeral progress/stream event during an invocation.
/// Added in 1.1. Events are fanned out to any client following this
/// invocation live (SubmitStream); they are NOT written to the
/// tamper-evident audit log. `name` is a caller-defined event label
/// (e.g. "progress", "token"); `payload` is the event body. The host
/// enforces per-invocation size + rate limits — an event over the
/// limit is dropped with a warning and never fails the invocation.
emit-event: func(name: string, payload: payload);
}
/// The core interface every module exports.