From b55222a7cf33c07915afb90f080aabeefcee7f46 Mon Sep 17 00:00:00 2001 From: Joshua Temple Date: Tue, 16 Jun 2026 12:29:20 -0400 Subject: [PATCH] docs: add stability policy + changelog index, sharpen cluster/wasm scope Add a root CHANGELOG.md that indexes each module's per-module changelog, and a STABILITY.md defining the stability labels used in the README modules table. Link both from the README Status section. There is no single global version (per-module SemVer), so the index makes the release surface discoverable. Sharpen two capability claims to match the code: - the cluster module row now notes the in-memory transport is the tested path, with the gRPC transport module behind the same interface (it is experimental), rather than implying a bundled, finished network layer; - the wasm overview notes that only a Go guest path is exercised today; the JSON ABI is language-agnostic but no non-Go guest SDK ships yet (roadmap #177). --- CHANGELOG.md | 37 ++++++++++++++++++++++++++ README.md | 5 +++- STABILITY.md | 32 ++++++++++++++++++++++ docs/src/content/docs/wasm/overview.md | 5 ++++ 4 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 CHANGELOG.md create mode 100644 STABILITY.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..228cde5 --- /dev/null +++ b/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//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) diff --git a/README.md b/README.md index 02ed593..84d3361 100644 --- a/README.md +++ b/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 diff --git a/STABILITY.md b/STABILITY.md new file mode 100644 index 0000000..6b2280a --- /dev/null +++ b/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). diff --git a/docs/src/content/docs/wasm/overview.md b/docs/src/content/docs/wasm/overview.md index 88b84a4..8b9ba26 100644 --- a/docs/src/content/docs/wasm/overview.md +++ b/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: