@telorun/sdk 0.77.0 → 0.80.0

package/dist/step-engine.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The step grammar and its execution: `invoke` / `value` / `if` / `while` /
+ * `switch` / `try` / `throw`, the `steps.<name>.result` accumulator, and the
+ * nested-scope walk that resolves an inline `invoke:` into a named resource.
+ *
+ * WHY THE SDK OWNS THIS. The leaf ({@link executeInvokeStep}) has always lived
+ * here; everything above it lived in `modules/run` for no reason anyone chose,
+ * and that is what made a step body something only `run`'s own kinds could have.
+ * `@telorun/sdk` is the single name in the bundle loader's `REALM_COLLAPSE_NAMES`
+ * — symlinked onto the KERNEL's own copy rather than inlined — so it is one
+ * version per process whatever anyone pins, and it is reachable from a controller
+ * bundle and from the kernel's own boot runner alike. A module library
+ * (`exports.code:`) is no longer copied per consumer, but it is still one scope
+ * per pinned version, it is outside the seam entirely for an npm-delivered
+ * controller, and the kernel cannot reach one at all. For a component whose
+ * contract is determinism across a durable run, one implementation is the whole
+ * premise.
+ *
+ * The context is STRUCTURAL ({@link StepEngineContext}), the property the leaf
+ * already proved: `ResourceContext` satisfies it, and so does a kernel-side
+ * adapter. Nothing here imports the kernel or `run`.
+ */
+import type { InvokeContext } from "./cancellation.js";
+import { type InvokeStep, type InvokeStepContext } from "./invoke-step.js";
+import type { KindRef, ScopeContext } from "./ref.js";
+/**
+ * What the engine needs beyond the leaf's own contract: turning an inline
+ * `invoke: { kind, … }` into a named reference.
+ *
+ * Widened from {@link InvokeStepContext} rather than replaced, so one interface
+ * describes a step site whether or not control flow is involved. Satisfied
+ * structurally by `ResourceContext`; a host that composes steps in code supplies
+ * its own.
+ */
+export interface StepEngineContext extends InvokeStepContext {
+    ensureKindRef(value: any, resourceName?: string): KindRef;
+}
+export interface IfStep {
+    name: string;
+    if: string;
+    then: Step[];
+    elseif?: Array<{
+        if: string;
+        then: Step[];
+    }>;
+    else?: Step[];
+}
+export interface WhileStep {
+    name: string;
+    while: string;
+    do: Step[];
+}
+export interface SwitchStep {
+    name: string;
+    switch: string;
+    cases: Record<string, Step[]>;
+    default?: Step[];
+}
+export interface TryStep {
+    name: string;
+    when?: string;
+    try: Step[];
+    catch?: Step[];
+    finally?: Step[];
+}
+export interface ThrowStep {
+    name: string;
+    throw: {
+        code: string;
+        message?: string;
+        data?: unknown;
+    };
+}
+export interface ValueStep {
+    name: string;
+    value: unknown;
+}
+export type Step = InvokeStep | IfStep | WhileStep | SwitchStep | TryStep | ThrowStep | ValueStep;
+/** Code assigned to any caught failure that is not a structured `InvokeError`.
+ *  Guarantees `error.code` is always a non-empty string inside a `catch`, so a
+ *  `throw: { code: "${{ error.code }}" }` rethrow can never resolve to null.
+ *  The analyzer's throws resolver mirrors this constant. */
+export declare const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
+/** The `error` variable a `catch:` / `catches:` branch sees. */
+export interface SequenceError {
+    message: string;
+    code: string;
+    data?: unknown;
+    step: string;
+}
+/**
+ * Who is running this body — the two facts the generated name of an inline
+ * `invoke:` is built from.
+ *
+ * Taken as identity rather than as a finished prefix because that name is
+ * MANIFEST-VISIBLE topology: it is what `steps.<name>.result`, a trace span and
+ * an `ERR_RESOURCE_NOT_FOUND` all print. Every caller used to spell the recipe
+ * itself (`` `Iteration${pascalCase(name)}` ``), which is the half of a
+ * must-not-fork component that forked anyway — the fifth composer would get the
+ * casing subtly wrong, or collide with the fourth.
+ */
+export interface StepBodyOwner {
+    /** The owning kind's suffix (`Sequence`, `Iteration`, `Transaction`). */
+    kind: string;
+    /** The owning resource's `metadata.name`. */
+    resourceName: string;
+}
+/** Runs a step list against an `extraCtx` CEL scope, owning the full grammar —
+ *  `invoke` / `value` / `if` / `while` / `switch` / `try` / `throw`. A composing
+ *  kind injects its own scope variables (`item`, `index`, `iteration`,
+ *  `previous`, …) through `extraCtx`; the engine knows none of them. */
+export declare class StepEngine {
+    private readonly ctx;
+    /** Prefix for generated inline-invoke resource names; unique per host resource
+     *  (`SequenceMySeq`, `LoopPollUntilReady`). */
+    private readonly namePrefix;
+    constructor(ctx: StepEngineContext, owner: StepBodyOwner);
+    resolveInvokes(stepList: Step[], path?: string[]): void;
+    private inlineInvokeResourceName;
+    /**
+     * @param path Journal key prefix for this list — see {@link stepPath}. A
+     *   composer that repeats a body (an iteration element, a loop turn) qualifies
+     *   it with the index, which is what makes each repetition an independently
+     *   resumable subtree. Omitted, it is derived from the ambient step path, so a
+     *   NESTED body nests its keys instead of restarting at the root — see
+     *   {@link baseStepPath}.
+     */
+    executeSteps(stepList: Step[], steps: Record<string, unknown>, scope: ScopeContext | undefined, extraCtx: Record<string, unknown>, invokeCtx?: InvokeContext, path?: string): Promise<void>;
+    /**
+     * The journal key of one step.
+     *
+     * Composed from the WRITTEN structure — the enclosing list's path plus this
+     * step's own name — never from execution order. A per-run call ordinal would
+     * be simpler and is wrong: two branches of a concurrent fan-out interleave
+     * their dispatches, so an ordinal numbers them differently on every run while
+     * these paths stay fixed.
+     */
+    private pathOf;
+    /** The run handle to journal through, or undefined when this body is not
+     *  inside a durable run — in which case the engine behaves exactly as it did
+     *  before durability existed, and pays nothing for it. */
+    private handle;
+    /**
+     * Evaluate a control-flow decision, journaling it when a run is durable.
+     *
+     * EVERY decision goes through here, which is the closure property the whole
+     * design rests on: a predicate, a loop condition and a switch key are all read
+     * from a CEL scope carrying live readings, so re-deriving one in a fresh
+     * process can send the replay down a different branch than the run took —
+     * silently, because the journal would then hand back a recorded result under a
+     * key the run reached for a different reason.
+     */
+    private decide;
+    private executeStep;
+    private executeIfStep;
+    private executeWhileStep;
+    private executeSwitchStep;
+    /** A pure step: expand the expression in the step scope and publish it as
+     *  `steps.<name>.result`, the same shape an invoke step records — so a
+     *  downstream step cannot tell how the value was produced. Nothing is
+     *  dispatched, so there is no span and no topology edge. */
+    private executeValueStep;
+    private executeThrowStep;
+    private executeTryStep;
+}
+/** Normalize any caught failure to the `error` shape a `catch:` branch reads.
+ *  Shared with the composers' whole-operation `catches:`, so one caught failure
+ *  has one shape wherever it is read. */
+export declare function toSequenceError(err: unknown, stepName: string): SequenceError;
+//# sourceMappingURL=step-engine.d.ts.map

package/dist/step-engine.d.ts.map

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

package/dist/step-engine.js

@@ -0,0 +1,365 @@
+/**
+ * The step grammar and its execution: `invoke` / `value` / `if` / `while` /
+ * `switch` / `try` / `throw`, the `steps.<name>.result` accumulator, and the
+ * nested-scope walk that resolves an inline `invoke:` into a named resource.
+ *
+ * WHY THE SDK OWNS THIS. The leaf ({@link executeInvokeStep}) has always lived
+ * here; everything above it lived in `modules/run` for no reason anyone chose,
+ * and that is what made a step body something only `run`'s own kinds could have.
+ * `@telorun/sdk` is the single name in the bundle loader's `REALM_COLLAPSE_NAMES`
+ * — symlinked onto the KERNEL's own copy rather than inlined — so it is one
+ * version per process whatever anyone pins, and it is reachable from a controller
+ * bundle and from the kernel's own boot runner alike. A module library
+ * (`exports.code:`) is no longer copied per consumer, but it is still one scope
+ * per pinned version, it is outside the seam entirely for an npm-delivered
+ * controller, and the kernel cannot reach one at all. For a component whose
+ * contract is determinism across a durable run, one implementation is the whole
+ * premise.
+ *
+ * The context is STRUCTURAL ({@link StepEngineContext}), the property the leaf
+ * already proved: `ResourceContext` satisfies it, and so does a kernel-side
+ * adapter. Nothing here imports the kernel or `run`.
+ */
+import { durableHandleOf, journalingSuppressed, stepPath, } from "./durable-run.js";
+import { isSuspension } from "./durable-suspension.js";
+import { InvokeError, isInvokeError } from "./invoke-error.js";
+import { executeInvokeStep } from "./invoke-step.js";
+/** Code assigned to any caught failure that is not a structured `InvokeError`.
+ *  Guarantees `error.code` is always a non-empty string inside a `catch`, so a
+ *  `throw: { code: "${{ error.code }}" }` rethrow can never resolve to null.
+ *  The analyzer's throws resolver mirrors this constant. */
+export const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
+function isInvokeStep(step) {
+    return "invoke" in step;
+}
+function isIfStep(step) {
+    return "if" in step;
+}
+function isWhileStep(step) {
+    return "while" in step;
+}
+function isSwitchStep(step) {
+    return "switch" in step;
+}
+function isTryStep(step) {
+    return "try" in step;
+}
+function isThrowStep(step) {
+    return "throw" in step;
+}
+function isValueStep(step) {
+    return "value" in step;
+}
+/** Runs a step list against an `extraCtx` CEL scope, owning the full grammar —
+ *  `invoke` / `value` / `if` / `while` / `switch` / `try` / `throw`. A composing
+ *  kind injects its own scope variables (`item`, `index`, `iteration`,
+ *  `previous`, …) through `extraCtx`; the engine knows none of them. */
+export class StepEngine {
+    ctx;
+    /** Prefix for generated inline-invoke resource names; unique per host resource
+     *  (`SequenceMySeq`, `LoopPollUntilReady`). */
+    namePrefix;
+    constructor(ctx, owner) {
+        this.ctx = ctx;
+        this.namePrefix = `${pascalCase(owner.kind)}${pascalCase(owner.resourceName)}`;
+    }
+    resolveInvokes(stepList, path = ["steps"]) {
+        for (const [index, step] of stepList.entries()) {
+            const stepPath = [...path, String(index)];
+            if (isInvokeStep(step)) {
+                const raw = step.invoke;
+                if (!raw || typeof raw.invoke !== "function") {
+                    step.invoke = this.ctx.ensureKindRef(raw, this.inlineInvokeResourceName(step.name, stepPath));
+                }
+            }
+            if (isIfStep(step)) {
+                this.resolveInvokes(step.then, [...stepPath, "then"]);
+                if (step.elseif) {
+                    for (const [elseifIndex, branch] of step.elseif.entries()) {
+                        this.resolveInvokes(branch.then, [...stepPath, "elseif", String(elseifIndex), "then"]);
+                    }
+                }
+                if (step.else)
+                    this.resolveInvokes(step.else, [...stepPath, "else"]);
+            }
+            if (isWhileStep(step))
+                this.resolveInvokes(step.do, [...stepPath, "do"]);
+            if (isSwitchStep(step)) {
+                for (const [caseName, branch] of Object.entries(step.cases)) {
+                    this.resolveInvokes(branch, [...stepPath, "cases", caseName]);
+                }
+                if (step.default)
+                    this.resolveInvokes(step.default, [...stepPath, "default"]);
+            }
+            if (isTryStep(step)) {
+                this.resolveInvokes(step.try, [...stepPath, "try"]);
+                if (step.catch)
+                    this.resolveInvokes(step.catch, [...stepPath, "catch"]);
+                if (step.finally)
+                    this.resolveInvokes(step.finally, [...stepPath, "finally"]);
+            }
+        }
+    }
+    inlineInvokeResourceName(stepName, stepPath) {
+        const path = stepPath.map(pascalCase).join("");
+        const step = pascalCase(stepName);
+        return `${this.namePrefix}${path}${step}`;
+    }
+    /**
+     * @param path Journal key prefix for this list — see {@link stepPath}. A
+     *   composer that repeats a body (an iteration element, a loop turn) qualifies
+     *   it with the index, which is what makes each repetition an independently
+     *   resumable subtree. Omitted, it is derived from the ambient step path, so a
+     *   NESTED body nests its keys instead of restarting at the root — see
+     *   {@link baseStepPath}.
+     */
+    async executeSteps(stepList, steps, scope, extraCtx, invokeCtx, path) {
+        const base = path ?? baseStepPath(invokeCtx);
+        for (const step of stepList) {
+            await this.executeStep(step, steps, scope, extraCtx, invokeCtx, base);
+        }
+    }
+    /**
+     * The journal key of one step.
+     *
+     * Composed from the WRITTEN structure — the enclosing list's path plus this
+     * step's own name — never from execution order. A per-run call ordinal would
+     * be simpler and is wrong: two branches of a concurrent fan-out interleave
+     * their dispatches, so an ordinal numbers them differently on every run while
+     * these paths stay fixed.
+     */
+    pathOf(path, step) {
+        // A missing name is refused rather than defaulted. The shared `Step` schema
+        // declares `name` required, so a manifest cannot reach this — but a caller
+        // assembling steps in code can, and an empty segment would give two such
+        // steps ONE journal key, where first-writer-wins hands the second the
+        // first's result. Silent, and indistinguishable from a correct replay.
+        if (!step.name) {
+            throw new InvokeError("ERR_STEP_NAME_REQUIRED", `A step at '${path}' has no name. A name is what identifies the step in the run's ` +
+                `record, so two unnamed steps would share one key and the second would be handed ` +
+                `the first's result.`, { path });
+        }
+        return stepPath(path, step.name);
+    }
+    /** The run handle to journal through, or undefined when this body is not
+     *  inside a durable run — in which case the engine behaves exactly as it did
+     *  before durability existed, and pays nothing for it. */
+    handle(invokeCtx) {
+        return durableHandleOf(invokeCtx);
+    }
+    /**
+     * Evaluate a control-flow decision, journaling it when a run is durable.
+     *
+     * EVERY decision goes through here, which is the closure property the whole
+     * design rests on: a predicate, a loop condition and a switch key are all read
+     * from a CEL scope carrying live readings, so re-deriving one in a fresh
+     * process can send the replay down a different branch than the run took —
+     * silently, because the journal would then hand back a recorded result under a
+     * key the run reached for a different reason.
+     */
+    async decide(invokeCtx, path, kind, compute) {
+        const handle = this.handle(invokeCtx);
+        if (!handle || journalingSuppressed(this.ctx, invokeCtx, handle))
+            return compute();
+        return handle.decide(path, kind, compute);
+    }
+    async executeStep(step, steps, scope, extraCtx, invokeCtx, path = "steps") {
+        const here = this.pathOf(path, step);
+        if (isInvokeStep(step))
+            await executeInvokeStep(step, this.ctx, {
+                steps,
+                scope,
+                cel: extraCtx,
+                invokeCtx,
+                journalPath: here,
+            });
+        else if (isIfStep(step))
+            await this.executeIfStep(step, steps, scope, extraCtx, invokeCtx, here);
+        else if (isWhileStep(step))
+            await this.executeWhileStep(step, steps, scope, extraCtx, invokeCtx, here);
+        else if (isSwitchStep(step))
+            await this.executeSwitchStep(step, steps, scope, extraCtx, invokeCtx, here);
+        else if (isTryStep(step))
+            await this.executeTryStep(step, steps, scope, extraCtx, invokeCtx, here);
+        else if (isThrowStep(step))
+            this.executeThrowStep(step, steps, extraCtx);
+        else if (isValueStep(step))
+            await this.executeValueStep(step, steps, extraCtx, invokeCtx, here);
+        else
+            throw new Error(`Step "${step.name}" has no recognized type key`);
+    }
+    async executeIfStep(step, steps, scope, extraCtx, invokeCtx, path = "steps") {
+        // Each predicate is journaled under its own key, so replay takes the branch
+        // the RUN took rather than the branch the predicate would evaluate to now.
+        if (await this.decide(invokeCtx, stepPath(path, "if"), "predicate", () => this.ctx.expandValue(step.if, { steps, ...extraCtx }))) {
+            await this.executeSteps(step.then, steps, scope, extraCtx, invokeCtx, stepPath(path, "then"));
+            return;
+        }
+        if (step.elseif) {
+            for (const [index, branch] of step.elseif.entries()) {
+                if (await this.decide(invokeCtx, stepPath(path, "elseif", index), "predicate", () => this.ctx.expandValue(branch.if, { steps, ...extraCtx }))) {
+                    await this.executeSteps(branch.then, steps, scope, extraCtx, invokeCtx, stepPath(path, "elseif", index, "then"));
+                    return;
+                }
+            }
+        }
+        if (step.else) {
+            await this.executeSteps(step.else, steps, scope, extraCtx, invokeCtx, stepPath(path, "else"));
+        }
+    }
+    async executeWhileStep(step, steps, scope, extraCtx, invokeCtx, path = "steps") {
+        // The turn index qualifies both the condition's key and the body's, so each
+        // turn is an independently resumable subtree and a resume re-enters the turn
+        // it stopped in rather than restarting the loop.
+        for (let turn = 0;; turn++) {
+            const go = await this.decide(invokeCtx, stepPath(path, "while", turn), "condition", () => this.ctx.expandValue(step.while, { steps, ...extraCtx }));
+            if (!go)
+                return;
+            await this.executeSteps(step.do, steps, scope, extraCtx, invokeCtx, stepPath(path, "do", turn));
+        }
+    }
+    async executeSwitchStep(step, steps, scope, extraCtx, invokeCtx, path = "steps") {
+        const key = String(await this.decide(invokeCtx, stepPath(path, "switch"), "switch", () => this.ctx.expandValue(step.switch, { steps, ...extraCtx })));
+        if (Object.prototype.hasOwnProperty.call(step.cases, key)) {
+            await this.executeSteps(step.cases[key], steps, scope, extraCtx, invokeCtx, stepPath(path, "cases", key));
+        }
+        else if (step.default) {
+            await this.executeSteps(step.default, steps, scope, extraCtx, invokeCtx, stepPath(path, "default"));
+        }
+        else {
+            throw new Error(`Switch step "${step.name}": no matching case for "${key}" and no default`);
+        }
+    }
+    /** A pure step: expand the expression in the step scope and publish it as
+     *  `steps.<name>.result`, the same shape an invoke step records — so a
+     *  downstream step cannot tell how the value was produced. Nothing is
+     *  dispatched, so there is no span and no topology edge. */
+    async executeValueStep(step, steps, extraCtx, invokeCtx, path = "steps") {
+        try {
+            // Journaled like any other decision: a pure step's expression may be
+            // impure (`now()`, `uuid()`), and its value becomes `steps.<name>.result`
+            // that later steps read — so re-deriving it on replay would change the
+            // run's state without any dispatch having differed. This is also what lets
+            // a `Durable.Value` work INSIDE a collapsed region: collapse suppresses
+            // per-step entries, never a direct decision.
+            const result = await this.decide(invokeCtx, path, "value", () => this.ctx.expandValue(step.value, { steps, ...extraCtx }));
+            steps[step.name] = { result };
+        }
+        catch (err) {
+            // A suspension is not this step's failure — it is the run leaving —
+            // so it passes through unattributed rather than being rewritten into an
+            // InvokeError a `catches:` list could name.
+            if (isSuspension(err))
+                throw err;
+            // Attribute the failure the way every other step branch does — a bare
+            // expression error names no step, no resource and no line, which is the
+            // one thing a `catch:` and a stack trace both need.
+            const failure = toSequenceError(err, step.name);
+            throw new InvokeError(failure.code, `Step "${step.name}": ${failure.message}`, {
+                step: step.name,
+                data: failure.data,
+            });
+        }
+    }
+    executeThrowStep(step, steps, extraCtx) {
+        const cel = { steps, ...extraCtx };
+        const expanded = this.ctx.expandValue(step.throw, cel);
+        const code = expanded?.code;
+        if (typeof code !== "string" || code.length === 0) {
+            // Structured error (not plain Error) so the failure stays in the InvokeError
+            // channel and a route's `catches:` list can still map it. The alternative —
+            // a plain Error — would skip catches: entirely and fall through to a 500.
+            throw new InvokeError("INVALID_THROW_STEP", `throw.code is required and must resolve to a non-empty string (step "${step.name}")`, { step: step.name, code });
+        }
+        const message = typeof expanded.message === "string" ? expanded.message : code;
+        throw new InvokeError(code, message, expanded.data);
+    }
+    async executeTryStep(step, steps, scope, extraCtx, invokeCtx, path = "steps") {
+        if (step.when !== undefined &&
+            !(await this.decide(invokeCtx, stepPath(path, "when"), "predicate", () => this.ctx.expandValue(step.when, { steps, ...extraCtx })))) {
+            return;
+        }
+        let tryFailed = false;
+        let tryError;
+        try {
+            await this.executeSteps(step.try, steps, scope, extraCtx, invokeCtx, stepPath(path, "try"));
+        }
+        catch (err) {
+            // `try:` must NOT catch a suspension. The signal unwinds to the workflow
+            // that owns the run; absorbing it here would run the `catch:` branch and
+            // then continue, converting a park into a completed step and duplicating
+            // every effect after it. The latch would catch that at the boundary, but
+            // a hard error is a worse answer than simply not swallowing it.
+            if (isSuspension(err))
+                throw err;
+            tryFailed = true;
+            tryError = err;
+        }
+        if (tryFailed) {
+            if (step.catch) {
+                const seqErr = toSequenceError(tryError, step.name);
+                try {
+                    await this.executeSteps(step.catch, steps, scope, { ...extraCtx, error: seqErr }, invokeCtx, stepPath(path, "catch"));
+                }
+                catch (catchErr) {
+                    if (step.finally) {
+                        await this.executeSteps(step.finally, steps, scope, { ...extraCtx, error: toSequenceError(catchErr, step.name) }, invokeCtx, stepPath(path, "finally"));
+                    }
+                    throw catchErr;
+                }
+                if (step.finally) {
+                    await this.executeSteps(step.finally, steps, scope, { ...extraCtx, error: null }, invokeCtx, stepPath(path, "finally"));
+                }
+            }
+            else {
+                if (step.finally) {
+                    await this.executeSteps(step.finally, steps, scope, { ...extraCtx, error: toSequenceError(tryError, step.name) }, invokeCtx, stepPath(path, "finally"));
+                }
+                throw tryError;
+            }
+        }
+        else if (step.finally) {
+            await this.executeSteps(step.finally, steps, scope, { ...extraCtx, error: null }, invokeCtx, stepPath(path, "finally"));
+        }
+    }
+}
+/** The naming recipe for a generated inline-invoke resource. Module-private: it
+ *  is the engine's own, and a bare `pascalCase` on the SDK's flat surface is a
+ *  utility nobody should be reimplementing a name from. */
+function pascalCase(s) {
+    return s
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((p) => p[0].toUpperCase() + p.slice(1))
+        .join("");
+}
+/** Normalize any caught failure to the `error` shape a `catch:` branch reads.
+ *  Shared with the composers' whole-operation `catches:`, so one caught failure
+ *  has one shape wherever it is read. */
+export function toSequenceError(err, stepName) {
+    if (isInvokeError(err)) {
+        // InvokeError.code is not validated non-empty at construction, so fall back
+        // to PLAIN_ERROR_CODE; message then falls back to the resolved code. Keeps
+        // both fields non-empty (see PLAIN_ERROR_CODE).
+        const code = err.code || PLAIN_ERROR_CODE;
+        return { message: err.message || code, code, data: err.data, step: stepName };
+    }
+    const message = (err instanceof Error ? err.message : String(err)) || "Unknown error";
+    return { message, code: PLAIN_ERROR_CODE, data: undefined, step: stepName };
+}
+/**
+ * Where a step list's journal keys hang from.
+ *
+ * At the top of a durable run there is no ambient path and the base is `steps`.
+ * Inside one, it is the path of the step that dispatched this body — so a nested
+ * sequence's `work` becomes `steps/importAll/work` rather than a second
+ * `steps/work`, and two nested bodies can no longer collide.
+ *
+ * The dispatching step's path is used directly rather than with a `steps`
+ * segment appended: the parent path already names one dispatch site, and every
+ * other segment the grammar produces (`then`, `do[2]`, `cases/x`) is distinct
+ * from a step name, so nothing else can generate the same key.
+ */
+function baseStepPath(invokeCtx) {
+    return invokeCtx?.durablePath ?? "steps";
+}

package/dist/zone-attribute.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Zone attributes — what an `x-telo-provides-zone` object form declares about
+ * the region a body slot establishes, and the single accessor every surface
+ * reads that vocabulary through (the `value-type.ts` precedent, itself the
+ * `ref-slot.ts` one).
+ *
+ * A body slot that CONSTRAINS its contents is a body slot that already
+ * ESTABLISHES a zone — a transaction, a lease, an idempotency claim, a durable
+ * run are all of them — so the constraints are attributes on the annotation
+ * rather than a second annotation family that would have to restate the zone's
+ * location, its `extends` resolution and its runtime open call.
+ *
+ * THE VOCABULARY IS DATA; THE MEANING IS THE CONSUMER'S. Entries live at
+ * `sdk/zone-attributes/*.json` (see the README there) and are copied in by the
+ * root `prepare`. Both kernels read the identical files, because `noSuspend` is
+ * what stops a run parking inside a lease wherever that run executes. An entry
+ * declares a name, a value schema and its `requires:` dependencies, and no code:
+ * there is nothing per entry to implement.
+ *
+ * THE SET IS CLOSED. `x-telo-ref`'s `use` is a closed set on the same annotation
+ * family and nothing has needed to extend it; capabilities and value types are
+ * closed. The argument for openness inverts on inspection — `metadata.categories`
+ * is open precisely because NOTHING BRANCHES ON IT, while every zone attribute
+ * exists to be branched on and every reader is core. And a third-party attribute
+ * could only ever be HALF an attribute: a module cannot contribute an analyzer
+ * pass, so it would get a runtime reader here and no static check, while the
+ * failure directions that justify validating this vocabulary at all — an unread
+ * `noSuspend`, an unread `atomic` — are exactly the ones only a static check
+ * catches.
+ *
+ * THE REGISTRY IS IN THE SDK for the reasons the value-type one is: it is
+ * dependency-free and Node-built-in-free (so the browser-side analyzer can read
+ * it), and it is the only placement a module controller can reach.
+ */
+import type { ZoneEntry } from "./cancellation.js";
+/** One zone attribute, exactly as its entry file declares it. */
+export interface ZoneAttributeEntry {
+    /** The bare name an author writes as a key inside the annotation. Bare rather
+     *  than `Telo.`-qualified because the position already implies the namespace
+     *  and a closed set has no second namespace to disambiguate against. */
+    readonly name: string;
+    /** JSON Schema the declared value must satisfy — always the author's REASON,
+     *  required by being the value itself rather than a sibling of a boolean. That
+     *  is also what makes a type check possible at all: there is no `true` to
+     *  accept, so `atomic: true` fails this schema. */
+    readonly value: Record<string, unknown>;
+    /** Attributes that must be declared alongside this one. Compiled to JSON
+     *  Schema's `dependentRequired`, so the completeness rule lives in the data
+     *  beside the thing it constrains rather than as a hardcoded pair of names. */
+    readonly requires: readonly string[];
+    readonly description: string;
+}
+/**
+ * Read one entry file's parsed data.
+ *
+ * Reading is STRICT and the vocabulary is closed at every level, for the reason
+ * the value-type reader is: a malformed or typo'd entry's only other outcome is
+ * an attribute that quietly is not in the vocabulary — which reads to an author
+ * as "unknown name", pointing at their manifest instead of at the entry.
+ */
+export declare function parseZoneAttributeEntry(file: string, data: unknown): ZoneAttributeEntry;
+/** Every declared zone attribute, keyed by its bare name. */
+export declare const ZONE_ATTRIBUTES: ReadonlyMap<string, ZoneAttributeEntry>;
+/** The declared names, in entry order — what a diagnostic listing the closed
+ *  vocabulary prints. */
+export declare function zoneAttributeNames(): string[];
+/**
+ * The attributes a zone declares, keyed by name, with the author's reason as the
+ * value.
+ *
+ * A typed record rather than a string-keyed bag, which the closed vocabulary is
+ * what makes possible. It is a readability gain and NOT a semantic one — the
+ * kernel still interprets nothing and branches on no name, exactly as
+ * `readRefSlot` hands back `use` without acting on it.
+ */
+export type ZoneAttributes = {
+    readonly [K in "atomic" | "idempotent" | "noSuspend" | "replayed"]?: string;
+};
+/**
+ * One open zone, paired with what it declares about everything inside it.
+ *
+ * The kind is carried so a consumer can name the zone in a diagnostic — "the
+ * `Sql.Transaction` you are inside forbids parking" — while the attributes are
+ * what it actually branches on.
+ */
+export interface OpenZoneAttributes {
+    /** Canonical `<module>.<Kind>` of the providing kind. */
+    readonly kind: string;
+    /** What this zone declares, with each author's reason as the value. */
+    readonly attributes: ZoneAttributes;
+    /** The open entry itself, so a consumer that must ASK something about this
+     *  particular zone has it in hand — a durable journal answering "do my writes
+     *  land inside your atomicity?" needs the entry, not the kind.
+     *
+     *  This is not the rejected "attributes on the entry" shape inverted: the
+     *  entry stays three identities and carries nothing new, it merely travels
+     *  BESIDE the attributes instead of being looked up again by a caller that
+     *  would have to re-walk the stack to find it. */
+    readonly entry: ZoneEntry;
+}
+//# sourceMappingURL=zone-attribute.d.ts.map

package/dist/zone-attribute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone-attribute.d.ts","sourceRoot":"","sources":["../src/zone-attribute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGnD,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC;;4EAEwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;uDAGmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;;mFAE+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAuBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,kBAAkB,CAyCvF;AAsCD,6DAA6D;AAC7D,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAmB,CAAC;AAExF;yBACyB;AACzB,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,CAAC,IAAI,QAAQ,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC,CAAC,EAAE,MAAM;CAC5E,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC;;;;;;;sDAOkD;IAClD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B"}