Skip to content

Commit 5c18df9

Browse files
joshua-templejoshua-temple
committed
docs: tighten README modules table and status for readability
Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
1 parent 43889f5 commit 5c18df9

1 file changed

Lines changed: 29 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 29 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -96,61 +96,38 @@ flowchart LR
9696
Each module is independently versioned (per-module SemVer) and carries its own
9797
stability label.
9898

99-
| Module | What it is | Status |
100-
| --------------------- | -------------------------------------------------------------------------------- | ------------ |
101-
| `state` | Full-featured, domain-agnostic statechart engine. Stdlib-only, no IO. | v1.0.0 |
102-
| `state/analysis` | Static model-checking and path enumeration over a machine's IR. | advisory |
103-
| `state/evolution` | Diffs two machine definitions and classifies the SemVer bump. | advisory |
104-
| `state/conformance` | Reusable harness for driving golden scenarios against a machine. | advisory |
105-
| `state/verify` | Decides behavioral properties of a machine and returns a witness event sequence. | advisory |
106-
| `state/expr` | Rich expression tier: CEL-backed guards type-checked against the context schema. | stable contract (v0.1.0) |
107-
| `gen` | Eject codegen: turn a machine's IR into typed Go stub source and a registry wiring. | v0.1.0 |
108-
| `cmd/crucible` | Headless IR CLI: lint, render, diff, validate, and eject a machine's serialized IR. | v0.1.0 |
109-
| `telemetry` | Vendor-neutral tracing/metrics interface for the IO modules. Stdlib-only. | experimental |
110-
| `telemetry/slog` | `log/slog` adapter for the telemetry interface. | experimental |
111-
| `telemetry/otel` | OpenTelemetry adapter for the telemetry interface. | experimental |
112-
| `telemetry/datadog` | Datadog adapter for the telemetry interface. | experimental |
113-
| `broker` | Message broker seam: publish/subscribe transport with injected adapters. | planned |
114-
| `sink` | Egress seam: fan emitted effects out to many destinations, fire-and-forget. | experimental |
115-
| `source` | Ingress seam: consume streams and drive statecharts; ack on durable transition. | experimental |
116-
| `source/kafka` | Kafka/RedPanda Inlet over franz-go: group consumer, mark-commit-after-process. | experimental |
117-
| `source/jetstream` | NATS JetStream Inlet over nats.go: pull consumer, ack/nak/term, MaxAckPending. | experimental |
118-
| `source/redis` | Redis Streams Inlet over go-redis: consumer group, XACK/pending-claim, DLQ. | experimental |
119-
| `source/cloudevents` | CloudEvents codec with structured and binary content modes. | experimental |
120-
| `source/cdc` | Change-data-capture codec: decode Debezium/OpenCDC change events, drive by key. | experimental |
121-
| `source/statemachine` | Bridge: an inbound message drives a transition, ack tied to the durable commit. | experimental |
122-
| `durable` | Durable-execution runtime: record and replay nondeterminism to survive a crash. | experimental |
123-
| `cluster` | Distribution runtime: remote actors, supervision, and live instance migration. | experimental |
124-
| `transport` | gRPC network transport for cluster: remote deliver/spawn and time-travel. | experimental |
125-
| `wasm` | Run state behaviors as WebAssembly: polyglot guards over a JSON ABI via wazero. | experimental |
126-
127-
source also ships composable reliability middleware as its own opt-in modules
128-
(`source/retry`, `source/dlq`, `source/idempotency`, `source/schema`) and an
129-
in-memory `source/memsource` test source, each experimental.
99+
| Module | What it is | Status |
100+
| ------------------- | ------------------------------------------------------------------------- | ------------------------ |
101+
| `state` | Domain-agnostic statechart engine. Stdlib-only, no IO. | v1.0.0 (stable) |
102+
| `state` subpackages | `analysis`, `evolution`, `conformance`, `verify`: diagnostics over the IR. | advisory |
103+
| `state/expr` | CEL-backed guards type-checked against the context schema. | stable contract (v0.1.0) |
104+
| `gen` | Eject codegen: a machine's IR into typed Go stubs and registry wiring. | v0.1.0 |
105+
| `cmd/crucible` | Headless IR CLI: lint, render, diff, validate, eject. | v0.1.0 |
106+
| `telemetry` | Vendor-neutral tracing/metrics seam, plus `slog`, `otel`, `datadog` adapters. | experimental |
107+
| `sink` | Egress fan-out, fire-and-forget. 20+ destinations: SQL, Dynamo, S3, Kafka, NATS, Redis, StatsD, … | experimental |
108+
| `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 |
109+
| `durable` | Durable-execution runtime: record and replay to survive a crash. | experimental |
110+
| `cluster` | Distribution runtime: remote actors, supervision, live migration (gRPC `transport`, `wasm` polyglot behaviors). | experimental |
111+
| `broker` | Message broker seam: publish/subscribe transport with injected adapters. | planned |
130112

131113
## Status
132114

133-
`state` is released at **v1.0.0**: a complete, embeddable statechart engine
134-
covering hierarchical, parallel, and final states, history, guard combinators,
135-
delayed transitions, invoked services, an actor model, snapshots, and JSON
136-
(de)serialization. Its public contract is frozen under v1 SemVer. The
137-
`analysis`, `evolution`, `conformance`, and `verify` subpackages ship inside
138-
v1.0 but are **advisory**: they produce diagnostics, and their surfaces sit
139-
outside the frozen contract and may change in a minor release. `state/expr` is a
140-
separate module pinned at v0.1.0 whose expression *semantics* are a committed,
141-
stable contract even though the module version is pre-1.0.
142-
143-
The IR tools `gen` (eject codegen) and `cmd/crucible` (the IR CLI) are released
144-
at **v0.1.0**, versioned independently of `state` and free to move at their own
145-
pace.
146-
147-
The remaining modules are still evolving and may change before they reach v1:
148-
`telemetry`, `sink`, and `source` (with all their adapters, codecs, and
149-
middleware) are released and documented, as are the host-side runtimes over the
150-
kernel: `durable` (durable execution), `cluster` (distribution and live
151-
migration), `transport` (the gRPC network transport for cluster), and `wasm`
152-
(polyglot behaviors). `broker` is planned. Treat those modules as experimental
153-
until each reaches its own v1.
115+
**`state` is released at v1.0.0 with a frozen public contract.** It is a
116+
complete, embeddable statechart engine: hierarchical, parallel, and final states,
117+
history, guard combinators, delayed transitions, invoked services, an actor
118+
model, snapshots, and JSON (de)serialization.
119+
120+
- **`state` subpackages** (`analysis`, `evolution`, `conformance`, `verify`):
121+
advisory. They ship inside v1.0 but sit outside the frozen contract and may
122+
change in a minor release.
123+
- **`state/expr`**: a separate module at v0.1.0. The module version is pre-1.0,
124+
but its expression *semantics* are a committed, stable contract.
125+
- **`gen` and `cmd/crucible`**: released at v0.1.0, versioned independently of
126+
`state` and free to move at their own pace.
127+
- **Everything else is experimental** and may change before it reaches v1:
128+
`telemetry`, `sink`, and `source` (with all adapters, codecs, and middleware),
129+
plus the host-side runtimes `durable`, `cluster`, `transport`, and `wasm`.
130+
`broker` is planned.
154131

155132
## Roadmap
156133

0 commit comments

Comments
 (0)