feat: sync stateful components to Spin v4 (WASI RC 2026-03-15)

Bump the spin-stateful-http world and its vendored WASI deps from
wasi:http/handler / wasi:clocks RC 2026-01-06 to 2026-03-15 to match Spin v4,
sync the vendored lifecycle.wit with the host, and add a stateful-counter
example (router + counter, addressed via spin.alt).

Validated end-to-end on a Spin v4 host: the example component builds with a
WASI-0.3-capable componentize-py (bytecodealliance/componentize-py#225) and
exports spin:stateful-component/lifecycle@0.1.0 +
wasi:http/handler@0.3.0-rc-2026-03-15; instantiate/suspend lifecycle,
per-instance isolation, and re-instantiation all work.

The p3 Handler/Lifecycle protocols in wit/exports remain hand-maintained stubs:
componentize-py 0.17.2 can't generate p3 stream bindings, and the WASI-0.3
componentize-py can't run the 'bindings' regen against wit/deps because the SDK
vendors multiple fermyon:spin versions. Building components works regardless.
See CONTRIBUTING.md and examples/spin-stateful/README.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: radu-matei

CONTRIBUTING.md

@@ -32,6 +32,28 @@ mv bindings/spin_sdk/wit/* src/spin_sdk/wit/
 rm -r bindings
 ```
 
+> **Note on stateful / WASI Preview 3 components.** The `spin-stateful-http`
+> world exports `wasi:http/handler@0.3.0-rc-2026-03-15`, whose request/response
+> bodies are `stream<u8>`. `componentize-py` 0.17.2 cannot regenerate bindings
+> for p3 stream types (it panics with `not yet implemented: Stream(...)`), so the
+> `Handler` and `Lifecycle` protocols in `src/spin_sdk/wit/exports/__init__.py`
+> are maintained by hand rather than regenerated by the command above.
+>
+> Building a stateful *component* (as opposed to regenerating bindings) requires
+> a `componentize-py` with WASI 0.3 support
+> ([bytecodealliance/componentize-py#225](https://github.com/bytecodealliance/componentize-py/pull/225)),
+> built from that branch until it is released. With it, build with:
+>
+> ```bash
+> componentize-py --all-features componentize -m spin_sdk=spin-stateful-http app -o app.wasm
+> ```
+>
+> Note: that newer `componentize-py` rejects the `bindings -d src/spin_sdk/wit`
+> regeneration above because the SDK vendors multiple `fermyon:spin` package
+> versions (`@2.0.0`, `@3.0.0`, unversioned) under `wit/deps`; consolidating
+> those to a single version is needed to regenerate (rather than hand-maintain)
+> the p3 bindings. See `examples/spin-stateful`.
+
 ### Updating docs
 
 Any time you regenerate the bindings or edit files by hand, you'll want to

examples/spin-stateful/README.md

@@ -0,0 +1,61 @@
+# Stateful counter (Python)
+
+A [stateful component](https://spinframework.dev): a long-lived, addressable
+Wasm instance. The runtime keeps one live instance per `(component, instance-id)`
+pair, calls the lifecycle hooks, and routes requests to it via the `spin.alt`
+addressing scheme. The count lives in memory across requests for the lifetime of
+the instance.
+
+```python
+from spin_sdk.stateful import stateful_component, Request, Response
+
+@stateful_component
+class Counter:
+    def __init__(self, id: str):       # called once on activation
+        self.id = id
+        self.count = 0
+
+    def suspend(self):                  # called before idle suspension (optional)
+        print(f"suspending counter {self.id} at {self.count}")
+
+    def handle_request(self, request: Request) -> Response:
+        self.count += 1
+        return Response(200, {"content-type": "text/plain"},
+                        f"counter {self.id} = {self.count}\n".encode())
+```
+
+Stateful components are not publicly routable; pair this with a router component
+that forwards `GET /<id>` to `https://spin.alt/component/counter/<id>/` (see the
+Rust SDK's `stateful-counter` example for a complete router + counter app).
+
+## Building
+
+> **Tooling requirement.** Stateful components export the WASI Preview 3 HTTP
+> handler (`wasi:http/handler@0.3.0-rc-2026-03-15`), whose bodies are
+> `stream<u8>`. This needs a `componentize-py` with WASI 0.3 support
+> ([bytecodealliance/componentize-py#225](https://github.com/bytecodealliance/componentize-py/pull/225)),
+> which is newer than the 0.17.2 pinned in `CONTRIBUTING.md`. Build it from that
+> branch until a release is available.
+
+```bash
+componentize-py --all-features componentize \
+    -m spin_sdk=spin-stateful-http \
+    app -o app.wasm
+```
+
+`-m spin_sdk=spin-stateful-http` selects the stateful world from the SDK's
+`componentize-py.toml` (which exposes several worlds), and `--all-features`
+enables the `@since`/`@unstable` WASI annotations. If the SDK isn't installed in
+the active environment, add `-p <path-to>/spin-python-sdk/src`.
+
+## Running end-to-end
+
+Pair this counter with a router (e.g. the Rust SDK's `stateful-counter` router)
+and run on a Spin v4 host:
+
+```bash
+spin up --stateful-idle-timeout 30s
+curl localhost:3000/alice   # counter alice = 1
+curl localhost:3000/alice   # counter alice = 2
+curl localhost:3000/bob     # counter bob = 1   (isolated per instance)
+```

examples/spin-stateful/app.py

@@ -0,0 +1,25 @@
+"""A stateful counter component.
+
+The runtime keeps one live instance per (component, instance-id) pair and
+routes requests to it via the spin.alt addressing scheme. The count lives in
+memory across requests for the lifetime of the instance.
+"""
+
+from spin_sdk.stateful import stateful_component, Request, Response
+
+
+@stateful_component
+class Counter:
+    def __init__(self, id: str):
+        # Called once when the runtime first activates this instance.
+        self.id = id
+        self.count = 0
+
+    def suspend(self):
+        # Called before the runtime suspends this instance (idle timeout).
+        print(f"suspending counter {self.id} at {self.count}")
+
+    def handle_request(self, request: Request) -> Response:
+        self.count += 1
+        body = f"counter {self.id} = {self.count}\n".encode()
+        return Response(200, {"content-type": "text/plain"}, body)

examples/spin-stateful/spin.toml

@@ -0,0 +1,16 @@
+spin_manifest_version = 2
+
+[application]
+name = "spin-stateful"
+version = "0.1.0"
+authors = ["The Spin authors"]
+description = "A stateful counter component addressed via spin.alt."
+
+# The counter has no trigger of its own; it is reached via the spin.alt
+# addressing scheme from another component (e.g. a router). See README.md.
+[component.counter]
+source = "app.wasm"
+stateful = true
+[component.counter.build]
+command = "componentize-py --all-features componentize -m spin_sdk=spin-stateful-http app -o app.wasm"
+watch = ["app.py"]

src/spin_sdk/wit/deps/clocks-0.3.0-rc-2026-01-06/clocks.wit

@@ -0,0 +1,48 @@
+package wasi:clocks@0.3.0-rc-2026-03-15;
+/// WASI Monotonic Clock is a clock API intended to let users measure elapsed
+/// time.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// A monotonic clock is a clock which has an unspecified initial value, and
+/// successive reads of the clock will produce non-decreasing values.
+@since(version = 0.3.0-rc-2026-03-15)
+interface monotonic-clock {
+    use types.{duration};
+
+    /// A mark on a monotonic clock is a number of nanoseconds since an
+    /// unspecified initial value, and can only be compared to instances from
+    /// the same monotonic-clock.
+    @since(version = 0.3.0-rc-2026-03-15)
+    type mark = u64;
+
+    /// Read the current value of the clock.
+    ///
+    /// The clock is monotonic, therefore calling this function repeatedly will
+    /// produce a sequence of non-decreasing values.
+    ///
+    /// For completeness, this function traps if it's not possible to represent
+    /// the value of the clock in a `mark`. Consequently, implementations
+    /// should ensure that the starting time is low enough to avoid the
+    /// possibility of overflow in practice.
+    @since(version = 0.3.0-rc-2026-03-15)
+    now: func() -> mark;
+
+    /// Query the resolution of the clock. Returns the duration of time
+    /// corresponding to a clock tick.
+    @since(version = 0.3.0-rc-2026-03-15)
+    get-resolution: func() -> duration;
+
+    /// Wait until the specified mark has occurred.
+    @since(version = 0.3.0-rc-2026-03-15)
+    wait-until: async func(
+        when: mark,
+    );
+
+    /// Wait for the specified duration to elapse.
+    @since(version = 0.3.0-rc-2026-03-15)
+    wait-for: async func(
+        how-long: duration,
+    );
+}

src/spin_sdk/wit/deps/clocks-0.3.0-rc-2026-03-15/monotonic-clock.wit

@@ -0,0 +1,51 @@
+package wasi:clocks@0.3.0-rc-2026-03-15;
+/// WASI System Clock is a clock API intended to let users query the current
+/// time. The clock is not necessarily monotonic as it may be reset.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// External references may be reset, so this clock is not necessarily
+/// monotonic, making it unsuitable for measuring elapsed time.
+///
+/// It is intended for reporting the current date and time for humans.
+@since(version = 0.3.0-rc-2026-03-15)
+interface system-clock {
+    use types.{duration};
+
+    /// An "instant", or "exact time", is a point in time without regard to any
+    /// time zone: just the time since a particular external reference point,
+    /// often called an "epoch".
+    ///
+    /// Here, the epoch is 1970-01-01T00:00:00Z, also known as
+    /// [POSIX's Seconds Since the Epoch], also known as [Unix Time].
+    ///
+    /// Note that even if the seconds field is negative, incrementing
+    /// nanoseconds always represents moving forwards in time.
+    /// For example, `{ -1 seconds, 999999999 nanoseconds }` represents the
+    /// instant one nanosecond before the epoch.
+    /// For more on various different ways to represent time, see
+    /// https://tc39.es/proposal-temporal/docs/timezone.html
+    ///
+    /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
+    /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
+    @since(version = 0.3.0-rc-2026-03-15)
+    record instant {
+        seconds: s64,
+        nanoseconds: u32,
+    }
+
+    /// Read the current value of the clock.
+    ///
+    /// This clock is not monotonic, therefore calling this function repeatedly
+    /// will not necessarily produce a sequence of non-decreasing values.
+    ///
+    /// The nanoseconds field of the output is always less than 1000000000.
+    @since(version = 0.3.0-rc-2026-03-15)
+    now: func() -> instant;
+
+    /// Query the resolution of the clock. Returns the smallest duration of time
+    /// that the implementation permits distinguishing.
+    @since(version = 0.3.0-rc-2026-03-15)
+    get-resolution: func() -> duration;
+}

src/spin_sdk/wit/deps/clocks-0.3.0-rc-2026-03-15/system-clock.wit

@@ -0,0 +1,46 @@
+package wasi:clocks@0.3.0-rc-2026-03-15;
+
+@unstable(feature = clocks-timezone)
+interface timezone {
+    @unstable(feature = clocks-timezone)
+    use system-clock.{instant};
+
+    /// Return the IANA identifier of the currently configured timezone. This
+    /// should be an identifier from the IANA Time Zone Database.
+    ///
+    /// For displaying to a user, the identifier should be converted into a
+    /// localized name by means of an internationalization API.
+    ///
+    /// If the implementation does not expose an actual timezone, or is unable
+    /// to provide mappings from times to deltas between the configured timezone
+    /// and UTC, or determining the current timezone fails, or the timezone does
+    /// not have an IANA identifier, this returns nothing.
+    @unstable(feature = clocks-timezone)
+    iana-id: func() -> option<string>;
+
+    /// The number of nanoseconds difference between UTC time and the local
+    /// time of the currently configured timezone, at the exact time of
+    /// `instant`.
+    ///
+    /// The magnitude of the returned value will always be less than
+    /// 86,400,000,000,000 which is the number of nanoseconds in a day
+    /// (24*60*60*1e9).
+    ///
+    /// If the implementation does not expose an actual timezone, or is unable
+    /// to provide mappings from times to deltas between the configured timezone
+    /// and UTC, or determining the current timezone fails, this returns
+    /// nothing.
+    @unstable(feature = clocks-timezone)
+    utc-offset: func(when: instant) -> option<s64>;
+
+    /// Returns a string that is suitable to assist humans in debugging whether
+    /// any timezone is available, and if so, which. This may be the same string
+    /// as `iana-id`, or a formatted representation of the UTC offset such as
+    /// `-04:00`, or something else.
+    ///
+    /// WARNING: The returned string should not be consumed mechanically! It may
+    /// change across platforms, hosts, or other implementation details. Parsing
+    /// this string is a major platform-compatibility hazard.
+    @unstable(feature = clocks-timezone)
+    to-debug-string: func() -> string;
+}

src/spin_sdk/wit/deps/clocks-0.3.0-rc-2026-03-15/timezone.wit

@@ -0,0 +1,8 @@
+package wasi:clocks@0.3.0-rc-2026-03-15;
+/// This interface common types used throughout wasi:clocks.
+@since(version = 0.3.0-rc-2026-03-15)
+interface types {
+    /// A duration of time, in nanoseconds.
+    @since(version = 0.3.0-rc-2026-03-15)
+    type duration = u64;
+}

src/spin_sdk/wit/deps/clocks-0.3.0-rc-2026-03-15/types.wit

@@ -0,0 +1,11 @@
+package wasi:clocks@0.3.0-rc-2026-03-15;
+
+@since(version = 0.3.0-rc-2026-03-15)
+world imports {
+    @since(version = 0.3.0-rc-2026-03-15)
+    import monotonic-clock;
+    @since(version = 0.3.0-rc-2026-03-15)
+    import system-clock;
+    @unstable(feature = clocks-timezone)
+    import timezone;
+}