@telorun/sdk 0.80.0 → 0.82.0

package/dist/capabilities/runnable.d.ts

@@ -1,11 +1,19 @@
 import type { InvokeContext } from "../cancellation.js";
+import type { EffectChain } from "../effect.js";
 export interface Runnable {
     /**
+     * Perform the resource's work, RETURNING the effects it leaves behind.
+     *
+     * A one-shot task that allocates nothing returns nothing. A service returns
+     * the chain that opened its socket and took its kernel hold, and the runtime
+     * unwinds it — at teardown, or immediately if a later step of the same `run()`
+     * fails. There is no `teardown()` to keep in step with it.
+     *
      * @param ctx  Out-of-band per-run context carrying the cancellation token.
      *   Optional — runnables that ignore it keep working unchanged. Long-lived
      *   targets (servers, loops) observe `ctx.cancellation` to stop early when the
      *   boot run is cancelled (e.g. SIGINT).
      */
-    run(ctx?: InvokeContext): Promise<void>;
+    run(ctx?: InvokeContext): Promise<EffectChain<unknown> | void> | EffectChain<unknown> | void;
 }
 //# sourceMappingURL=runnable.d.ts.map

package/dist/capabilities/runnable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runnable.d.ts","sourceRoot":"","sources":["../../src/capabilities/runnable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC"}
+{"version":3,"file":"runnable.d.ts","sourceRoot":"","sources":["../../src/capabilities/runnable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9F"}

package/dist/effect.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Revertible effects — the module-author half of the lifecycle.
+ *
+ * An effect is a forward action paired with the inverse that undoes it.
+ * `init()` and `run()` RETURN the effects they perform, as a chain built with
+ * `ctx.effect(...)`, and the runtime executes it, keeps the inverses per
+ * lifecycle entry, and unwinds them last-in-first-out. There is no `teardown()`:
+ * the signature is what stops "what undoes this" from being forgotten, which an
+ * optional second method never did.
+ *
+ * Normative contract: `kernel/specs/revertible-effects.md`.
+ */
+/**
+ * An action's undo. Runs when its frame unwinds, or early via
+ * {@link EffectHandle.dispose}.
+ *
+ * Returns `unknown` rather than `void`: the runtime awaits whatever it gets and
+ * ignores it, and a great many disposal calls return something incidental
+ * (`client.quit()` → `"OK"`). Requiring `void` would have every author wrap a
+ * one-line inverse in a block for no gain.
+ */
+export type Inverse = () => unknown;
+/**
+ * What a forward action produces: its value, and what undoes it.
+ *
+ * `inverse` is OPTIONAL, and omitting it is a statement rather than a shortcut:
+ * this step allocated nothing that outlives a failure. A chain is also the
+ * sequencing structure for lifecycle work — a step that must run after the one
+ * before it — so a step with genuinely nothing to undo is a normal shape, and
+ * forcing `() => {}` would make "nothing to undo" indistinguishable from "the
+ * author forgot the undo", which is the one thing this mechanism exists to tell
+ * apart.
+ */
+export interface EffectOutcome<T> {
+    result: T;
+    inverse?: Inverse;
+}
+/**
+ * The forward action, given the previous step's result.
+ *
+ * Either form is accepted, and the single-outcome case is the degenerate
+ * iterator. Reach for the generator when one step allocates several things that
+ * can fail between them: each `yield` registers that allocation's inverse the
+ * moment it completed, so a body that throws halfway — or is stopped by a
+ * teardown at a step boundary — recovers exactly what it did.
+ */
+export type EffectBody<TIn, TOut> = ((input: TIn) => Promise<EffectOutcome<TOut>>) | ((input: TIn) => AsyncGenerator<Inverse, TOut, void>);
+/**
+ * A lazy, ordered description of the effects a lifecycle entry performs.
+ *
+ * **Lazy**: nothing runs until the runtime executes what `init()` / `run()`
+ * returned, so sequencing and recovery belong to the runtime rather than to each
+ * controller — and the chain stays a description, which is what a second runtime
+ * can execute rather than reimplement.
+ *
+ * **Deliberately not a thenable**: an `async` function unwraps a promise-like on
+ * the way out, so a thenable chain returned from `async init()` would reach the
+ * runtime as its last step's *result*. Keeping it plain means `async init()`
+ * works and a controller may `await` freely before returning the chain.
+ *
+ * A chain is a value, so branches and loops build it like any other:
+ *
+ * ```ts
+ * let chain = ctx.effect("core", …);
+ * if (resource.cors) chain = chain.effect("cors", …);
+ * for (const mount of mounts) chain = chain.effect(`mount ${mount.path}`, …);
+ * return chain;
+ * ```
+ */
+export interface EffectChain<T> {
+    /** Extend the chain. `body` receives the previous step's result — which is how
+     *  an inverse gets the handle it has to close, without a field on the instance
+     *  existing only to carry it between the two halves. */
+    effect<TNext>(reason: string, body: EffectBody<T, TNext>): EffectChain<TNext>;
+    /**
+     * Execute the chain NOW against the resource's current frame, instead of
+     * returning it for the runtime to execute.
+     *
+     * The imperative door, and the one spelling for an allocation whose lifetime
+     * is an *operation* rather than the resource: `Durable.Workflow` takes a hold
+     * inside `invoke()` and releases it when the run settles or parks, which no
+     * returned chain can express because `invoke` returns the caller's value.
+     * Explicit rather than implicit (a thenable) — laziness is the property the
+     * returned form rests on, and a chain that ran when awaited would make "did
+     * this execute?" depend on whether someone happened to await it.
+     */
+    perform(): Promise<EffectResult<T>>;
+}
+export interface EffectHandle {
+    /**
+     * Run this effect's inverse now and take it off its frame — for an allocation
+     * whose lifetime is an *operation* rather than the resource (a hold taken per
+     * durable run, released when the run settles or parks).
+     *
+     * Idempotent, and a disposed effect is skipped when the frame unwinds. Order
+     * is unconstrained: a frame is a recovery order, not a dependency graph, so
+     * disposing something a later effect still depends on is the author's error —
+     * the runtime cannot see inside an inverse, and cascading would defeat the
+     * case early disposal exists for.
+     */
+    dispose(): Promise<void>;
+}
+/** What an imperative `ctx.effect(...)` awaits to: the value, plus the way to
+ *  end that one allocation early. */
+export interface EffectResult<T> extends EffectHandle {
+    readonly result: T;
+}
+//# sourceMappingURL=effect.d.ts.map

package/dist/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,MAAM,EAAE,CAAC,CAAC;IACV,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,CAAC,GAAG,EAAE,IAAI,IAC5B,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,GAC9C,CAAC,CAAC,KAAK,EAAE,GAAG,KAAK,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;;4DAEwD;IACxD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAC9E;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;OAUG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;qCACqC;AACrC,MAAM,WAAW,YAAY,CAAC,CAAC,CAAE,SAAQ,YAAY;IACnD,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB"}

package/dist/effect.js

@@ -0,0 +1,13 @@
+/**
+ * Revertible effects — the module-author half of the lifecycle.
+ *
+ * An effect is a forward action paired with the inverse that undoes it.
+ * `init()` and `run()` RETURN the effects they perform, as a chain built with
+ * `ctx.effect(...)`, and the runtime executes it, keeps the inverses per
+ * lifecycle entry, and unwinds them last-in-first-out. There is no `teardown()`:
+ * the signature is what stops "what undoes this" from being forgotten, which an
+ * optional second method never did.
+ *
+ * Normative contract: `kernel/specs/revertible-effects.md`.
+ */
+export {};

package/dist/evaluation-context.d.ts

@@ -128,6 +128,9 @@ export interface EvaluationContext {
     hasManifest(name: string): boolean;
     registerManifest(resource: ResourceManifest): void;
     spawnChild<T extends EvaluationContext>(child: T): T;
+    /** The inverse of {@link spawnChild}, for a child whose owner is being
+     *  discarded rather than torn down in place. */
+    detachChild(child: EvaluationContext): void;
     /** Spawn a fresh child context attached to this one — the isolated scope a
      *  templated definition registers its `resources:` into. Rooted here so child
      *  kinds/refs resolve against THIS context's imports (the defining library),

package/dist/evaluation-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluation-context.d.ts","sourceRoot":"","sources":["../src/evaluation-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evaluation-context.d.ts","sourceRoot":"","sources":["../src/evaluation-context.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export * from "./controller-context.js";
 export * from "./controller-policy.js";
 export * from "./evaluation-context.js";
 export * from "./module-context.js";
+export * from "./effect.js";
 export * from "./resource-context.js";
 export * from "./resource-instance.js";
 export * from "./resource-manifest.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -17,6 +17,7 @@ export * from "./controller-context.js";
 export * from "./controller-policy.js";
 export * from "./evaluation-context.js";
 export * from "./module-context.js";
+export * from "./effect.js";
 export * from "./resource-context.js";
 export * from "./resource-instance.js";
 export * from "./resource-manifest.js";

package/dist/resource-context.d.ts

@@ -1,4 +1,5 @@
 import type { CancellationSource, InvokeContext, OpenSpan, OpenSpanOptions, ZoneEntry } from "./cancellation.js";
+import type { EffectBody, EffectChain } from "./effect.js";
 import type { ResourceHandle } from "./resource-instance.js";
 import { ControllerContext } from "./controller-context.js";
 import type { Logger } from "./logger.js";
@@ -70,6 +71,42 @@ export interface ResourceContext extends ControllerContext {
      *  registers them into, so two instances of the same templated kind don't
      *  collide and the children nest under their parent in a debug view. */
     readonly ownerPrefix: string;
+    /**
+     * Describe a revertible action: `body` does the work and yields the inverse
+     * that undoes it. Returns a LAZY chain — `.effect(...)` extends it, threading
+     * each step's result into the next.
+     *
+     * Return the chain from `init()` / `run()`: the runtime executes it and keeps
+     * the inverses on that lifecycle entry's frame, unwinding them newest-first
+     * when the resource is torn down or when a later step fails. That is the whole
+     * of a controller's cleanup — there is no `teardown()`.
+     *
+     * Call `.perform()` instead when the allocation belongs to an *operation*
+     * rather than to the resource (a hold taken per durable run, released when the
+     * run settles or parks): it executes against the resource's current frame and
+     * hands back a {@link EffectResult} whose `dispose()` ends that one allocation.
+     * Such an effect MUST be disposed when its operation ends, or it accumulates
+     * for the resource's lifetime.
+     *
+     * `reason` names the effect in recovery diagnostics.
+     */
+    effect<T>(reason: string, body: EffectBody<void, T>): EffectChain<T>;
+    /**
+     * Hold the kernel open (a listening server, a run in flight); the returned
+     * closure releases it.
+     *
+     * The closure is a bare inverse and is NOT registered for you — which frame
+     * owns a hold is a fact only the caller has. Place it in a chain:
+     *
+     * ```ts
+     * ctx.effect("kernel hold", async () => ({ result: undefined, inverse: ctx.acquireHold() }))
+     * ```
+     *
+     * A hold whose lifetime is one *operation* rather than the resource (one per
+     * durable run, taken inside `invoke()`) is performed instead and disposed when
+     * that operation ends. A hold that is neither placed nor released keeps the
+     * process alive.
+     */
     acquireHold(reason?: string): () => void;
     /**
      * Report this resource's **observed state** — what it has learned while

package/dist/resource-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-context.d.ts","sourceRoot":"","sources":["../src/resource-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource-context.d.ts","sourceRoot":"","sources":["../src/resource-context.ts"],"names":[],"mappings":"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"}

package/dist/resource-instance.d.ts

@@ -1,10 +1,22 @@
 import type { Invocable } from "./capabilities/invokable.js";
 import type { Provider } from "./capabilities/provider.js";
 import type { Runnable } from "./capabilities/runnable.js";
+import type { EffectChain } from "./effect.js";
 import type { ResourceContext } from "./resource-context.js";
 export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<Invocable<TInput, TOutput>> & Partial<Runnable> & Partial<Provider<TOutput>> & {
-    init?(ctx?: ResourceContext): Promise<void>;
-    teardown?(): void | Promise<void>;
+    /**
+     * Build the resource, RETURNING the effects that built it.
+     *
+     * The chain is what undoes this — the runtime executes it, keeps the
+     * inverses, and unwinds them when the resource is torn down or when a later
+     * step of `init()` itself fails. Returning nothing is legal only for a
+     * resource that allocates nothing; there is no `teardown()`, so an
+     * allocation with no inverse is one nothing will ever reclaim.
+     *
+     * The chain is lazy and is not a thenable, so `async init()` may `await`
+     * whatever it needs before returning it.
+     */
+    init?(ctx: ResourceContext): EffectChain<unknown> | void | Promise<EffectChain<unknown> | void>;
     snapshot?(): Record<string, any> | Promise<Record<string, any>>;
     /**
      * Teardown ordering hint. Instances tear down in ascending priority — a

package/dist/resource-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG;IAC3B,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAChE;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEJ;;mBAEmB;AACnB,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;;gDAGgD;AAChD,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAErF;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;CAC3B;AAED,eAAO,MAAM,YAAY,GAAI,GAAG,cAAc,EAAE,GAAG,cAAc,KAAG,OAAwB,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,MAAuC,CAAC;AAE1E;sFACsF;AACtF,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,SAAS,GACjB,IAAI,CAaN;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAExE"}
+{"version":3,"file":"resource-instance.d.ts","sourceRoot":"","sources":["../src/resource-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CACjF,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAC3B,GACC,OAAO,CAAC,QAAQ,CAAC,GACjB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG;IAC3B;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,CAAC,GAAG,EAAE,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAChG,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAChE;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEJ;;mBAEmB;AACnB,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;;gDAGgD;AAChD,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAErF;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,kBAAkB,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;CAC3B;AAED,eAAO,MAAM,YAAY,GAAI,GAAG,cAAc,EAAE,GAAG,cAAc,KAAG,OAAwB,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,MAAuC,CAAC;AAE1E;sFACsF;AACtF,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,SAAS,GACjB,IAAI,CAaN;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAExE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sdk",
-  "version": "0.80.0",
+  "version": "0.82.0",
   "description": "Telo SDK - Public API for Telo module authors.",
   "keywords": [
     "telo",

package/src/capabilities/runnable.ts

@@ -1,11 +1,19 @@
 import type { InvokeContext } from "../cancellation.js";
+import type { EffectChain } from "../effect.js";
 
 export interface Runnable {
   /**
+   * Perform the resource's work, RETURNING the effects it leaves behind.
+   *
+   * A one-shot task that allocates nothing returns nothing. A service returns
+   * the chain that opened its socket and took its kernel hold, and the runtime
+   * unwinds it — at teardown, or immediately if a later step of the same `run()`
+   * fails. There is no `teardown()` to keep in step with it.
+   *
    * @param ctx  Out-of-band per-run context carrying the cancellation token.
    *   Optional — runnables that ignore it keep working unchanged. Long-lived
    *   targets (servers, loops) observe `ctx.cancellation` to stop early when the
    *   boot run is cancelled (e.g. SIGINT).
    */
-  run(ctx?: InvokeContext): Promise<void>;
+  run(ctx?: InvokeContext): Promise<EffectChain<unknown> | void> | EffectChain<unknown> | void;
 }

package/src/effect.ts

@@ -0,0 +1,115 @@
+/**
+ * Revertible effects — the module-author half of the lifecycle.
+ *
+ * An effect is a forward action paired with the inverse that undoes it.
+ * `init()` and `run()` RETURN the effects they perform, as a chain built with
+ * `ctx.effect(...)`, and the runtime executes it, keeps the inverses per
+ * lifecycle entry, and unwinds them last-in-first-out. There is no `teardown()`:
+ * the signature is what stops "what undoes this" from being forgotten, which an
+ * optional second method never did.
+ *
+ * Normative contract: `kernel/specs/revertible-effects.md`.
+ */
+
+/**
+ * An action's undo. Runs when its frame unwinds, or early via
+ * {@link EffectHandle.dispose}.
+ *
+ * Returns `unknown` rather than `void`: the runtime awaits whatever it gets and
+ * ignores it, and a great many disposal calls return something incidental
+ * (`client.quit()` → `"OK"`). Requiring `void` would have every author wrap a
+ * one-line inverse in a block for no gain.
+ */
+export type Inverse = () => unknown;
+
+/**
+ * What a forward action produces: its value, and what undoes it.
+ *
+ * `inverse` is OPTIONAL, and omitting it is a statement rather than a shortcut:
+ * this step allocated nothing that outlives a failure. A chain is also the
+ * sequencing structure for lifecycle work — a step that must run after the one
+ * before it — so a step with genuinely nothing to undo is a normal shape, and
+ * forcing `() => {}` would make "nothing to undo" indistinguishable from "the
+ * author forgot the undo", which is the one thing this mechanism exists to tell
+ * apart.
+ */
+export interface EffectOutcome<T> {
+  result: T;
+  inverse?: Inverse;
+}
+
+/**
+ * The forward action, given the previous step's result.
+ *
+ * Either form is accepted, and the single-outcome case is the degenerate
+ * iterator. Reach for the generator when one step allocates several things that
+ * can fail between them: each `yield` registers that allocation's inverse the
+ * moment it completed, so a body that throws halfway — or is stopped by a
+ * teardown at a step boundary — recovers exactly what it did.
+ */
+export type EffectBody<TIn, TOut> =
+  | ((input: TIn) => Promise<EffectOutcome<TOut>>)
+  | ((input: TIn) => AsyncGenerator<Inverse, TOut, void>);
+
+/**
+ * A lazy, ordered description of the effects a lifecycle entry performs.
+ *
+ * **Lazy**: nothing runs until the runtime executes what `init()` / `run()`
+ * returned, so sequencing and recovery belong to the runtime rather than to each
+ * controller — and the chain stays a description, which is what a second runtime
+ * can execute rather than reimplement.
+ *
+ * **Deliberately not a thenable**: an `async` function unwraps a promise-like on
+ * the way out, so a thenable chain returned from `async init()` would reach the
+ * runtime as its last step's *result*. Keeping it plain means `async init()`
+ * works and a controller may `await` freely before returning the chain.
+ *
+ * A chain is a value, so branches and loops build it like any other:
+ *
+ * ```ts
+ * let chain = ctx.effect("core", …);
+ * if (resource.cors) chain = chain.effect("cors", …);
+ * for (const mount of mounts) chain = chain.effect(`mount ${mount.path}`, …);
+ * return chain;
+ * ```
+ */
+export interface EffectChain<T> {
+  /** Extend the chain. `body` receives the previous step's result — which is how
+   *  an inverse gets the handle it has to close, without a field on the instance
+   *  existing only to carry it between the two halves. */
+  effect<TNext>(reason: string, body: EffectBody<T, TNext>): EffectChain<TNext>;
+  /**
+   * Execute the chain NOW against the resource's current frame, instead of
+   * returning it for the runtime to execute.
+   *
+   * The imperative door, and the one spelling for an allocation whose lifetime
+   * is an *operation* rather than the resource: `Durable.Workflow` takes a hold
+   * inside `invoke()` and releases it when the run settles or parks, which no
+   * returned chain can express because `invoke` returns the caller's value.
+   * Explicit rather than implicit (a thenable) — laziness is the property the
+   * returned form rests on, and a chain that ran when awaited would make "did
+   * this execute?" depend on whether someone happened to await it.
+   */
+  perform(): Promise<EffectResult<T>>;
+}
+
+export interface EffectHandle {
+  /**
+   * Run this effect's inverse now and take it off its frame — for an allocation
+   * whose lifetime is an *operation* rather than the resource (a hold taken per
+   * durable run, released when the run settles or parks).
+   *
+   * Idempotent, and a disposed effect is skipped when the frame unwinds. Order
+   * is unconstrained: a frame is a recovery order, not a dependency graph, so
+   * disposing something a later effect still depends on is the author's error —
+   * the runtime cannot see inside an inverse, and cascading would defeat the
+   * case early disposal exists for.
+   */
+  dispose(): Promise<void>;
+}
+
+/** What an imperative `ctx.effect(...)` awaits to: the value, plus the way to
+ *  end that one allocation early. */
+export interface EffectResult<T> extends EffectHandle {
+  readonly result: T;
+}

package/src/evaluation-context.ts

@@ -162,6 +162,9 @@ export interface EvaluationContext {
   hasManifest(name: string): boolean;
   registerManifest(resource: ResourceManifest): void;
   spawnChild<T extends EvaluationContext>(child: T): T;
+  /** The inverse of {@link spawnChild}, for a child whose owner is being
+   *  discarded rather than torn down in place. */
+  detachChild(child: EvaluationContext): void;
   /** Spawn a fresh child context attached to this one — the isolated scope a
    *  templated definition registers its `resources:` into. Rooted here so child
    *  kinds/refs resolve against THIS context's imports (the defining library),

package/src/index.ts

@@ -17,6 +17,7 @@ export * from "./controller-context.js";
 export * from "./controller-policy.js";
 export * from "./evaluation-context.js";
 export * from "./module-context.js";
+export * from "./effect.js";
 export * from "./resource-context.js";
 export * from "./resource-instance.js";
 export * from "./resource-manifest.js";

package/src/resource-context.ts

@@ -5,6 +5,7 @@ import type {
   OpenSpanOptions,
   ZoneEntry,
 } from "./cancellation.js";
+import type { EffectBody, EffectChain } from "./effect.js";
 import type { ResourceHandle } from "./resource-instance.js";
 import { ControllerContext } from "./controller-context.js";
 import type { Logger } from "./logger.js";
@@ -86,6 +87,42 @@ export interface ResourceContext extends ControllerContext {
    *  registers them into, so two instances of the same templated kind don't
    *  collide and the children nest under their parent in a debug view. */
   readonly ownerPrefix: string;
+  /**
+   * Describe a revertible action: `body` does the work and yields the inverse
+   * that undoes it. Returns a LAZY chain — `.effect(...)` extends it, threading
+   * each step's result into the next.
+   *
+   * Return the chain from `init()` / `run()`: the runtime executes it and keeps
+   * the inverses on that lifecycle entry's frame, unwinding them newest-first
+   * when the resource is torn down or when a later step fails. That is the whole
+   * of a controller's cleanup — there is no `teardown()`.
+   *
+   * Call `.perform()` instead when the allocation belongs to an *operation*
+   * rather than to the resource (a hold taken per durable run, released when the
+   * run settles or parks): it executes against the resource's current frame and
+   * hands back a {@link EffectResult} whose `dispose()` ends that one allocation.
+   * Such an effect MUST be disposed when its operation ends, or it accumulates
+   * for the resource's lifetime.
+   *
+   * `reason` names the effect in recovery diagnostics.
+   */
+  effect<T>(reason: string, body: EffectBody<void, T>): EffectChain<T>;
+  /**
+   * Hold the kernel open (a listening server, a run in flight); the returned
+   * closure releases it.
+   *
+   * The closure is a bare inverse and is NOT registered for you — which frame
+   * owns a hold is a fact only the caller has. Place it in a chain:
+   *
+   * ```ts
+   * ctx.effect("kernel hold", async () => ({ result: undefined, inverse: ctx.acquireHold() }))
+   * ```
+   *
+   * A hold whose lifetime is one *operation* rather than the resource (one per
+   * durable run, taken inside `invoke()`) is performed instead and disposed when
+   * that operation ends. A hold that is neither placed nor released keeps the
+   * process alive.
+   */
   acquireHold(reason?: string): () => void;
   /**
    * Report this resource's **observed state** — what it has learned while

package/src/resource-instance.ts

@@ -1,6 +1,7 @@
 import type { Invocable } from "./capabilities/invokable.js";
 import type { Provider } from "./capabilities/provider.js";
 import type { Runnable } from "./capabilities/runnable.js";
+import type { EffectChain } from "./effect.js";
 import type { ResourceContext } from "./resource-context.js";
 
 export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Partial<
@@ -8,8 +9,19 @@ export type ResourceInstance<TInput = Record<string, any>, TOutput = any> = Part
 > &
   Partial<Runnable> &
   Partial<Provider<TOutput>> & {
-    init?(ctx?: ResourceContext): Promise<void>;
-    teardown?(): void | Promise<void>;
+    /**
+     * Build the resource, RETURNING the effects that built it.
+     *
+     * The chain is what undoes this — the runtime executes it, keeps the
+     * inverses, and unwinds them when the resource is torn down or when a later
+     * step of `init()` itself fails. Returning nothing is legal only for a
+     * resource that allocates nothing; there is no `teardown()`, so an
+     * allocation with no inverse is one nothing will ever reclaim.
+     *
+     * The chain is lazy and is not a thenable, so `async init()` may `await`
+     * whatever it needs before returning it.
+     */
+    init?(ctx: ResourceContext): EffectChain<unknown> | void | Promise<EffectChain<unknown> | void>;
     snapshot?(): Record<string, any> | Promise<Record<string, any>>;
     /**
      * Teardown ordering hint. Instances tear down in ascending priority — a