docs: add stability policy + changelog index, sharpen cluster/wasm scope

CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+Crucible uses **per-module SemVer**: each module is released and versioned on its
+own line, so there is no single global version number. Each module keeps its own
+`CHANGELOG.md` next to its code; this file is an index to them. See
+[STABILITY.md](STABILITY.md) for what each module's stability label means.
+
+## Stable
+
+- [`state`](state/CHANGELOG.md) — statechart engine (v1.x, frozen contract)
+- [`state/expr`](state/expr/CHANGELOG.md) — CEL-backed guards
+
+## Tooling
+
+- [`gen`](gen/CHANGELOG.md) — eject codegen
+- [`cmd/crucible`](cmd/crucible/CHANGELOG.md) — headless IR CLI
+
+## Host-side runtimes (experimental)
+
+- [`durable`](durable/CHANGELOG.md) — durable-execution runtime
+- [`cluster`](cluster/CHANGELOG.md) — distribution runtime
+- [`wasm`](wasm/CHANGELOG.md) — WebAssembly guard runtime
+- [`telemetry`](telemetry/CHANGELOG.md) — tracing/metrics seam
+  ([`datadog`](telemetry/datadog/CHANGELOG.md), [`otel`](telemetry/otel/CHANGELOG.md) adapters)
+
+## IO edges (experimental)
+
+- [`sink`](sink/CHANGELOG.md) — egress fan-out. Each adapter keeps its own changelog
+  under `sink/<name>/CHANGELOG.md` (bridge, cloudwatch, dynamo, eventbridge, file,
+  firehose, gcppubsub, http, kafka, kinesis, nats, otel, prometheus, redis, s3, slog,
+  sns, sql, sqs, statsd, timestream).
+- `source` — ingress. Per-inlet changelogs:
+  [`kafka`](source/kafka/CHANGELOG.md), [`statemachine`](source/statemachine/CHANGELOG.md).
+
+## Examples
+
+- [`examples/dispatch`](examples/dispatch/CHANGELOG.md)

README.md

@@ -107,7 +107,7 @@ stability label.
 | `sink`              | Egress fan-out, fire-and-forget. 20+ destinations: SQL, Dynamo, S3, Kafka, NATS, Redis, StatsD, … | experimental             |
 | `source`            | Ingress: consume streams and drive machines, ack on durable transition. Inlets: Kafka, JetStream, Redis, CloudEvents, CDC; opt-in retry/DLQ/idempotency/schema middleware. | experimental             |
 | `durable`           | Durable-execution runtime: record and replay to survive a crash.         | experimental             |
-| `cluster`           | Distribution runtime: remote actors, supervision, and live migration (gRPC `transport` network layer included). | experimental             |
+| `cluster`           | Distribution runtime: remote actors, supervision, and live migration over a pluggable transport (in-memory transport tested; gRPC `transport` module behind the same interface). | experimental             |
 | `wasm`              | Run state behaviors as WebAssembly: polyglot guards over a JSON ABI via wazero. | experimental             |
 | `broker`            | Message broker seam: publish/subscribe transport with injected adapters.  | planned                  |
 
@@ -130,6 +130,9 @@ model, snapshots, and JSON (de)serialization.
   plus the host-side runtimes `durable`, `cluster`, `transport`, and `wasm`.
   `broker` is planned.
 
+See **[STABILITY.md](STABILITY.md)** for what each label promises, and
+**[CHANGELOG.md](CHANGELOG.md)** for the per-module release index.
+
 ## Roadmap
 
 Two kinds of seam frame the work ahead, and both build on the engine without

STABILITY.md

@@ -0,0 +1,32 @@
+# Stability policy
+
+Crucible is a multi-module repository. **Every module is versioned independently
+on its own SemVer line and keeps its own `CHANGELOG.md`** — there is no single
+global version. This document defines the stability labels used in the
+[Modules table](README.md#modules); that table is the live source for which label
+each module currently carries.
+
+## Labels
+
+| Label | What it promises |
+| --- | --- |
+| **stable (v1.x)** | Frozen public contract. Breaking changes only in a new major version. `state` is here. |
+| **stable contract (pre-1.0)** | The module version is still `v0.x`, but a named part of its behavior is a committed contract that will not break silently. `state/expr` commits its expression *semantics* this way. |
+| **released (v0.x)** | Released and usable, versioned independently, free to move at its own pace. Being pre-1.0, a minor release may still break. `gen` and `cmd/crucible` are here. |
+| **advisory** | Ships inside a stable module but sits *outside* its frozen contract and may change in a minor release. The `state` subpackages (`analysis`, `evolution`, `conformance`, `verify`) are advisory. |
+| **experimental** | Usable, tested, and benchmarked, but the API may change before it reaches v1. Pin a version and expect churn. The IO edges (`sink`, `source`) and host-side runtimes (`durable`, `cluster`, `transport`, `wasm`, `telemetry`) are experimental. |
+| **planned** | Not yet implemented. `broker` is planned. |
+
+## Using pre-1.0 modules
+
+The experimental and released-pre-1.0 modules are real implementations — tested and
+benchmarked, not stubs. The label is about *contract stability*, not quality: pin an
+exact version, read the module's `CHANGELOG.md` before upgrading, and expect the API
+to move until the module graduates to v1.
+
+## Graduation to v1
+
+Promoting an experimental module to v1 means committing to a frozen public contract
+under the same terms as `state`. The graduation criteria and a per-module
+compatibility matrix are tracked in
+[issue #179](https://github.com/stablekernel/crucible/issues/179).

docs/src/content/docs/wasm/overview.md

@@ -22,6 +22,11 @@ stdlib-only core: a deployment that uses only Go or CEL guards never compiles WA
 in. The ABI is **core WebAssembly**, not the Component Model, which would require a
 CGo runtime.
 
+> **Today, only a Go guest path is exercised.** The JSON ABI is language-agnostic
+> by design, but the only guest the test suite compiles is Go (`//go:wasmexport`); a
+> guest in another language must implement the two-export ABI directly. Ready-made
+> non-Go guest SDKs are [tracked on the roadmap](https://github.com/stablekernel/crucible/issues/177).
+
 ## The shape of it
 
 Compile a module once and reuse it across calls, then bind it as a guard by name: