0.2.0

.site/docs/core-concepts/canvas.md

@@ -9,12 +9,15 @@ This guide walks through Stem's task composition primitives—chains, groups, an
 chords—using in-memory brokers and backends. Each snippet references a runnable
 file under `packages/stem/example/docs_snippets/` so you can experiment locally
 with `dart run`. If you bootstrap with `StemApp`, use `app.canvas` to reuse the
-same broker, backend, task handlers, and encoder registry.
+same broker, backend, task handlers, and encoder registry. `StemApp` lazy-starts
+its managed worker for canvas dispatch too, so the common path does not need an
+explicit `await app.start()`.
 
 ## Chains
 
 Chains execute tasks serially. Each step receives the previous result via
-`context.meta['chainPrevResult']`.
+`context.meta`, so prefer typed reads like
+`context.meta.valueOr<String>('chainPrevResult', 'fallback')` over raw casts.
 
 ```dart file=<rootDir>/../packages/stem/example/docs_snippets/lib/canvas_chain.dart#canvas-chain
 
@@ -46,16 +49,19 @@ state:
 
 ## Chords
 
-Chords combine a group with a callback. Once all body tasks succeed, the callback
-runs with `context.meta['chordResults']` populated.
+Chords combine a group with a callback. Once all body tasks succeed, the
+callback runs with `context.meta['chordResults']` populated. Prefer
+`context.meta.valueListOr<T>('chordResults', const [])` over manual list casts
+when reading those results.
 
 ```dart file=<rootDir>/../packages/stem/example/docs_snippets/lib/canvas_chord.dart#canvas-chord
 
 ```
 
 If any branch fails, the callback is skipped and the chord group is marked as
-failed. Inspect `backend.getGroup(chordId)` to see which branch failed before
-retrying.
+failed. Inspect the latest group status via `StemApp.getGroupStatus(...)` or
+`StemClient.getGroupStatus(...)` before retrying. If you are operating below
+the runtime layer, read the raw backend directly.
 
 ## Dependency semantics
 
@@ -71,7 +77,10 @@ retrying.
 - `Canvas.group` returns a `GroupDispatch` with a result stream for each child.
 - `Canvas.chord` preserves the original signature order when building
   `chordResults`, so you can map results back to inputs deterministically.
-- `backend.getGroup(groupId)` returns the latest status for each child task.
+- `StemApp.getGroupStatus(...)` and `StemClient.getGroupStatus(...)` return the
+  latest status for each child task. Use `status.resultValues<T>()` for scalar
+  child results or `status.resultJson(...)` / `status.resultAs(codec: ...)` for
+  DTO payloads before dropping down to raw backend reads.
 
 ## Removal semantics
 
@@ -89,8 +98,8 @@ dart run lib/canvas_group.dart
 dart run lib/canvas_chord.dart
 ```
 
-Each script bootstraps a `StemApp` in-memory runtime, starts a worker, and then
-uses `app.canvas` for composition.
+Each script bootstraps a `StemApp` in-memory runtime and then uses `app.canvas`
+for composition.
 
 ## Best practices
 

.site/docs/core-concepts/cli-control.md

@@ -119,7 +119,7 @@ ensure the CLI and workers share the same task-definition entrypoint so task
 names, encoders, and routing rules stay consistent.
 
 A common pattern is to build that CLI registry from the same shared task list
-or generated `stemModule.tasks` your app uses, so task metadata stays consistent
+or generated `stemModule` your app uses, so task metadata stays consistent
 without teaching registry-first bootstrap for normal services.
 
 If a command needs a registry and none is available, it will exit with an error

.site/docs/core-concepts/observability.md

@@ -58,6 +58,19 @@ control-plane commands.
 
 ```
 
+When you inspect `TaskPostrunPayload` or `TaskSuccessPayload` directly, prefer
+`payload.resultJson(...)`, `payload.resultVersionedJson(...)`, or
+`payload.resultAs(codec: ...)` over manual
+`payload.result as Map<String, Object?>` casts.
+For workflow lifecycle signals, prefer
+`payload.metadataJson('key', ...)`,
+`payload.metadataVersionedJson('key', ...)`, or
+`payload.metadataAs('key', codec: ...)` over manual
+`payload.metadata['key'] as Map<String, Object?>` casts. If the entire
+metadata map is one DTO, use `payload.metadataPayloadJson(...)`,
+`payload.metadataPayloadVersionedJson(...)`, or
+`payload.metadataPayloadAs(codec: ...)` instead.
+
 ## Workflow Introspection
 
 Workflow runtimes can emit execution events (started/completed/failed/retrying)
@@ -80,6 +93,25 @@ class LoggingWorkflowIntrospectionSink implements WorkflowIntrospectionSink {
 }
 ```
 
+When a completed step or checkpoint carries a DTO payload, prefer
+`event.resultJson(...)`, `event.resultVersionedJson(...)`, or
+`event.resultAs(codec: ...)` over manual
+`event.result as Map<String, Object?>` casts.
+Step and runtime introspection events also expose typed metadata helpers via
+`event.metadataJson('key', ...)`, `event.metadataVersionedJson('key', ...)`,
+`event.metadataAs('key', codec: ...)`, `event.metadataPayloadJson(...)`, and
+`event.metadataPayloadVersionedJson(...)`.
+When worker events carry structured `data`, prefer `event.dataJson(...)`,
+`event.dataVersionedJson(...)`, or `event.dataAs(codec: ...)` over manual
+`event.data!['key']` casts. For completed control commands, use
+`payload.responseJson(...)`, `payload.responseVersionedJson(...)`,
+`payload.responseAs(codec: ...)`, `payload.errorJson(...)`,
+`payload.errorVersionedJson(...)`, or `payload.errorAs(codec: ...)` instead of
+walking raw `response` / `error` maps.
+Persisted worker heartbeats expose the same typed decode path on `extras` via
+`heartbeat.extrasJson(...)`, `heartbeat.extrasVersionedJson(...)`, and
+`heartbeat.extrasAs(codec: ...)`.
+
 ## Logging
 
 Use `stemLogger` (Contextual logger) for structured logs.
@@ -88,6 +120,11 @@ Use `stemLogger` (Contextual logger) for structured logs.
 
 ```
 
+The shared `stemLogger` starts silent by default, so opt in explicitly with
+`configureStemLogging(level: Level.info, format: StemLogFormat.pretty)`.
+When you want machine-oriented output for production log shipping, switch to
+`configureStemLogging(format: StemLogFormat.plain)`.
+
 Workers automatically include attempt, queue, and worker id in log contexts when
 `StemSignals` are enabled.
 

.site/docs/core-concepts/persistence.md

@@ -9,6 +9,11 @@ Use persistence when you need durable task state, workflow state, shared
 schedules, or revocation storage. Stem ships with Redis, Postgres, and SQLite
 adapters plus in-memory variants for local development.
 
+For the normal path, prefer `StemClient.inMemory(...)`,
+`StemClient.fromUrl(...)`, or a reusable `StemStack.fromUrl(...).createClient(...)`.
+Drop to `StemClient.create(...)` only when you really need custom broker or
+backend factories that the adapter stack cannot express.
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 

.site/docs/core-concepts/producer.md

@@ -5,13 +5,18 @@ sidebar_position: 2
 slug: /core-concepts/producer
 ---
 
-Enqueue tasks from your Dart services using `Stem.enqueue`. Start with the
-in-memory broker, then opt into Redis/Postgres as needed.
+Enqueue tasks from your Dart services through a `TaskEnqueuer` surface such as
+`StemClient`, `StemApp`, or `StemWorkflowApp`. Start with the in-memory broker,
+then opt into Redis/Postgres as needed.
+
+For adapter-backed deployments, prefer `StemClient.fromUrl(...)` or
+`StemStack.fromUrl(...).createClient(...)`. Keep `StemClient.create(...)` for
+the rarer case where you must provide custom factories directly.
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-## Enqueue tasks
+## Raw Enqueue
 
 <Tabs>
 <TabItem value="in-memory" label="In-memory (bin/producer.dart)">
@@ -39,19 +44,30 @@ import TabItem from '@theme/TabItem';
 
 ## Typed Enqueue Helpers
 
-When you need compile-time guarantees for task arguments and result types, wrap
-your handler in a `TaskDefinition`. The definition knows how to encode args and
-decode results, and exposes a fluent builder for overrides (headers, meta,
-options, scheduling):
+For the common producer path, prefer `TaskDefinition<TArgs, TResult>`. The
+definition owns argument encoding, result decoding, and default publish
+metadata, while exposing direct helpers and a fluent builder for overrides
+(headers, meta, options, scheduling):
 
 ```dart title="bin/producer_typed.dart" file=<rootDir>/../packages/stem/example/docs_snippets/lib/producer.dart#producer-typed
 
 ```
 
 Typed helpers are also available on `Canvas` (`definition.toSignature`) so
-group/chain/chord APIs produce strongly typed `TaskResult<T>` streams.
-Need to tweak headers/meta/queue at call sites? Wrap the definition in a
-`TaskEnqueueBuilder` and invoke `await builder.enqueueWith(stem);`.
+group/chain/chord APIs produce strongly typed `TaskResult<T>` streams. Need to
+tweak headers/meta/queue at call sites? Start from
+`definition.buildCall(args, ...)` when you need the explicit advanced
+transport path.
+
+Raw task-name strings still work, but they are the lower-level interop path.
+Reach for them when the task name is truly dynamic or you are crossing a
+boundary that does not have the generated/manual `TaskDefinition`. When those
+calls already have typed DTO args, prefer
+`enqueuer.enqueueValue(name, dto, codec: ...)` over hand-building an `args`
+map.
+If you later inspect the raw `Envelope`, prefer `envelope.argsJson(...)`,
+`envelope.argsVersionedJson(...)`, `envelope.metaJson(...)`, or
+`envelope.metaVersionedJson(...)` over manual map casts.
 
 ## Enqueue options
 
@@ -68,7 +84,7 @@ unsupported.
 Example:
 
 ```dart
-await stem.enqueue(
+await enqueuer.enqueue(
   'tasks.email',
   args: {'to': 'ops@example.com'},
   enqueueOptions: TaskEnqueueOptions(
@@ -86,7 +102,8 @@ await stem.enqueue(
 
 ## Tips
 
-- Reuse a single `Stem` instance; create it during application bootstrap.
+- Reuse a single `TaskEnqueuer` implementation; in most apps that means
+  `StemClient`, `StemApp`, or `StemWorkflowApp`.
 - Capture the returned task id when you need to poll status from the result backend.
 - Use `TaskOptions` to set queue, retries, priority, isolation, and visibility timeouts.
 - `meta` is stored with result backend entries—great for audit trails.

.site/docs/core-concepts/queue-events.md

@@ -14,11 +14,22 @@ Use this when you need lightweight event streams for domain notifications
 ## API Surface
 
 - `QueueEventsProducer.emit(queue, eventName, payload, headers, meta)`
+- `QueueEventsProducer.emitValue(queue, eventName, value, codec, headers, meta)`
+- `QueueEventsProducer.emitJson(queue, eventName, dto, headers, meta)`
+- `QueueEventsProducer.emitVersionedJson(queue, eventName, dto, version, headers, meta)`
 - `QueueEvents.start()` / `QueueEvents.close()`
 - `QueueEvents.events` stream (all events for that queue)
 - `QueueEvents.on(eventName)` stream (filtered by name)
 
 All events are delivered as `QueueCustomEvent`, which implements `StemEvent`.
+Use `event.payloadValue(...)` / `event.requiredPayloadValue(...)` to read typed
+payload fields instead of repeating raw `payload['key']` casts.
+If one queue event maps to one DTO, use `event.payloadJson(...)`,
+`event.payloadVersionedJson(...)`, or `event.payloadAs(codec: ...)` to decode
+the whole payload in one step.
+If the whole queue-event metadata map is one DTO, use `event.metaJson(...)`,
+`event.metaVersionedJson(...)`, or `event.metaAs(codec: ...)` instead of
+manual `event.meta[...]` casts.
 
 ## Producer + Listener
 
@@ -38,6 +49,13 @@ Multiple listeners on the same queue receive each emitted event.
 
 - Events are queue-scoped: listeners receive only events for their configured
   queue.
+- `emitValue(...)` is the codec-backed path when the payload should be
+  authored as a typed object but still use a custom map encoder or explicit
+  `PayloadCodec<T>`.
+- `emitJson(...)` is the DTO convenience path when the payload already exposes
+  `toJson()`.
+- `emitVersionedJson(...)` is the same convenience path when the payload
+  schema should persist an explicit `__stemPayloadVersion`.
 - `on(eventName)` matches exact event names.
 - `headers` and `meta` round-trip to listeners.
 - Event names and queue names must be non-empty.

.site/docs/core-concepts/signing.md

@@ -23,7 +23,8 @@ reason.
 ## How signing works in Stem
 
 - Producers create a `PayloadSigner` from environment-derived config and pass it
-  into `Stem` to sign new envelopes.
+  into the producer runtime (`StemClient` or raw `Stem`) to sign new
+  envelopes.
 - Workers create the same signer (or verification-only config) and pass it into
   `Worker` to verify each delivery.
 - Schedulers/Beat that enqueue tasks should also sign.
@@ -46,8 +47,10 @@ export STEM_SIGNING_ACTIVE_KEY=v1
 
 2) Wire the signer into producers, workers, and schedulers.
 
-These snippets come from the `packages/stem/example/microservice` project so you can see the
-full context.
+These snippets come from the `packages/stem/example/microservice` project so you
+can see the full context. They intentionally show the lower-level signing
+plumbing; for the normal happy path, still prefer `StemClient`/`StemApp`
+bootstrap.
 
 <Tabs>
 <TabItem value="producer" label="Producer (enqueuer): sign outgoing envelopes">