omkit 0.2.1 → 0.2.2

package/README.md

@@ -197,6 +197,7 @@ An Activity exposes its declared events plus the lifecycle ones (`done`, `error`
 
 - **`activity.on(event, handler)`** — subscribe to every emit.
 - **`activity.once(event)`** — a **promise** for the next emit; resolves `undefined` if the Activity settles first, so an `await` never hangs. A retained snapshot (like `healthy`) is replayed immediately even if you subscribe late.
+- **`activity.once("done")`** is the exception — it awaits the outcome itself: resolves the result on success, **rejects** on failure or cancellation (and observes the failure). That makes `await step().once("done")` a hard gate: a failed step throws at the `await`, in your body, instead of letting the orchestration sail past it. Use `.result` when a failure is an outcome you want to branch on rather than a stop.
 
 ```ts
 const probe = healthcheck({ url: "http://localhost:3000" });

package/dist/core/ActionRun.js

@@ -114,7 +114,11 @@ export class ActionRun {
         if (key === "error")
             this.observed = true;
         if (key === "done") {
-            return this.settled.promise.then((v) => v, () => undefined);
+            // Awaiting completion IS observing the outcome: deliver a failure to the awaiter
+            // (reject, like `.ref`) instead of resolving `undefined` and letting the body
+            // sail past a failed step while the unobserved-failure teardown races it.
+            this.observed = true;
+            return this.settled.promise;
         }
         return new Promise((resolve) => {
             let done = false;

package/dist/core/types.d.ts

@@ -92,7 +92,12 @@ export interface Activity<Result = unknown, Events extends object = NoEvents, Ha
     handleFailure(handler: (error: unknown) => void): this;
     /** Subscribe to every emit of a declared/system event (`done`/`error`/`attached`). */
     on<K extends keyof InstanceEvents<Events, Result>>(key: K, handler: EventHandler<InstanceEvents<Events, Result>[K]>): void;
-    /** Next emit of `key`; resolves `undefined` if the node settles first (never rejects). */
+    /**
+     * Next emit of `key`; resolves `undefined` if the node settles first (never rejects).
+     * Exception — `once("done")` awaits the outcome itself: it resolves the result on
+     * success and **rejects** on failure/cancellation (observing the failure), so
+     * `await activity.once("done")` is a hard step-gate the body cannot sail past.
+     */
     once<K extends keyof InstanceEvents<Events, Result>>(key: K): Promise<InstanceEvents<Events, Result>[K] | undefined>;
     /** Tag this run; chainable. */
     tag(name: string): this;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",