@telorun/sdk 0.75.0 → 0.79.0

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/type-schema-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-schema-ref.d.ts","sourceRoot":"","sources":["../src/type-schema-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElF;AAED;;;;;;wBAMwB;AACxB,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,GACX;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKjD;AAiBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqCzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAKjE"}
+{"version":3,"file":"type-schema-ref.d.ts","sourceRoot":"","sources":["../src/type-schema-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElF;AAED;;;;;;wBAMwB;AACxB,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,GACX;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKjD;AAyBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA6CzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAKjE"}

package/dist/type-schema-ref.js

@@ -55,6 +55,14 @@ const STRUCTURAL_KEYS = new Set([
     "properties",
     "required",
     "additionalProperties",
+    // `$defs` is a NAMESPACE, not a value: last-wins would drop every definition
+    // the other side declared, and a `$ref` pointing at one would then resolve to
+    // nothing. That is not hypothetical — a schema-valued slot is localized to
+    // `#/$defs/telo:<Fragment>` and hoisted here, so a child declaring any `$defs`
+    // of its own would erase the parent's hoisted entry and leave the parent's
+    // slots pointing at a definition that no longer exists.
+    "$defs",
+    "definitions",
     "allOf",
     "oneOf",
     "anyOf",
@@ -85,6 +93,7 @@ const STRUCTURAL_KEYS = new Set([
 export function mergeTypeSchemas(schemas) {
     const out = {};
     const properties = {};
+    const defs = { $defs: {}, definitions: {} };
     const required = new Set();
     let additionalProperties;
     let hasAdditionalProperties = false;
@@ -101,6 +110,11 @@ export function mergeTypeSchemas(schemas) {
         const props = schema.properties;
         if (props && typeof props === "object")
             Object.assign(properties, props);
+        for (const key of ["$defs", "definitions"]) {
+            const declared = schema[key];
+            if (declared && typeof declared === "object")
+                Object.assign(defs[key], declared);
+        }
         const req = schema.required;
         if (Array.isArray(req))
             for (const name of req)
@@ -121,6 +135,10 @@ export function mergeTypeSchemas(schemas) {
     }
     if (Object.keys(properties).length > 0)
         out.properties = properties;
+    for (const key of ["$defs", "definitions"]) {
+        if (Object.keys(defs[key]).length > 0)
+            out[key] = defs[key];
+    }
     if (required.size > 0)
         out.required = [...required];
     if (hasAdditionalProperties)

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"}

package/dist/zone-attribute.js

@@ -0,0 +1,130 @@
+/**
+ * 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 { ZONE_ATTRIBUTE_ENTRY_FILES } from "./zone-attributes/entries/index.js";
+class ZoneAttributeEntryError extends Error {
+    constructor(file, detail) {
+        super(`Invalid zone-attribute entry '${file}': ${detail}`);
+        this.name = "ZoneAttributeEntryError";
+    }
+}
+const ENTRY_KEYS = ["name", "value", "requires", "description", "$comment"];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(file, node, key) {
+    const value = node[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ZoneAttributeEntryError(file, `'${key}' must be a non-empty string`);
+    }
+    return value;
+}
+/**
+ * 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 function parseZoneAttributeEntry(file, data) {
+    if (!isPlainObject(data))
+        throw new ZoneAttributeEntryError(file, "an entry must be a mapping");
+    for (const key of Object.keys(data)) {
+        if (!ENTRY_KEYS.includes(key)) {
+            throw new ZoneAttributeEntryError(file, `an entry has no key '${key}'. Known keys: ${ENTRY_KEYS.join(", ")}.`);
+        }
+    }
+    const name = requireString(file, data, "name");
+    // Bare names, checked here rather than left to convention: a qualified one
+    // would be a key nothing resolves, and the closed set has nothing to qualify
+    // against.
+    if (!/^[a-z][A-Za-z0-9]*$/.test(name)) {
+        throw new ZoneAttributeEntryError(file, `'name' must be a bare camelCase word — the annotation position already implies ` +
+            `the namespace, and a closed set has no second namespace to qualify against`);
+    }
+    if (!isPlainObject(data.value)) {
+        throw new ZoneAttributeEntryError(file, "'value' must be a JSON Schema mapping");
+    }
+    const requires = data.requires === undefined ? [] : data.requires;
+    if (!Array.isArray(requires) || requires.some((r) => typeof r !== "string" || !r)) {
+        throw new ZoneAttributeEntryError(file, "'requires' must be a sequence of attribute names");
+    }
+    if (requires.includes(name)) {
+        throw new ZoneAttributeEntryError(file, `'requires' names '${name}' itself`);
+    }
+    return {
+        name,
+        value: data.value,
+        requires: requires,
+        description: requireString(file, data, "description"),
+    };
+}
+function buildRegistry() {
+    const registry = new Map();
+    for (const [file, data] of ZONE_ATTRIBUTE_ENTRY_FILES) {
+        const entry = parseZoneAttributeEntry(file, data);
+        if (registry.has(entry.name)) {
+            throw new ZoneAttributeEntryError(file, `'${entry.name}' is already declared by another entry`);
+        }
+        registry.set(entry.name, entry);
+    }
+    // A `requires:` naming an attribute no entry declares would compile to a
+    // `dependentRequired` clause nothing can ever satisfy, so every declaration of
+    // the depending attribute would be rejected with no way to fix it. Checked
+    // after the whole set is read, since entries are order-independent.
+    for (const entry of registry.values()) {
+        for (const dependency of entry.requires) {
+            if (!registry.has(dependency)) {
+                throw new ZoneAttributeEntryError(`${entry.name}.json`, `'requires' names '${dependency}', which no entry declares`);
+            }
+        }
+    }
+    // Defence in depth against the packaging mistake, whose failure is
+    // indistinguishable from an author's typo: every declared attribute becomes an
+    // unknown name, reported against manifests that are correct.
+    if (registry.size === 0) {
+        throw new Error("The zone-attribute vocabulary is empty. `sdk/zone-attributes/*.json` did not reach " +
+            "this build — check the file allowlist of whatever packaged it. Continuing would " +
+            "report every declared attribute as an unknown name, while enforcing none of them.");
+    }
+    return registry;
+}
+/** Every declared zone attribute, keyed by its bare name. */
+export const ZONE_ATTRIBUTES = buildRegistry();
+/** The declared names, in entry order — what a diagnostic listing the closed
+ *  vocabulary prints. */
+export function zoneAttributeNames() {
+    return [...ZONE_ATTRIBUTES.keys()];
+}

package/dist/zone-attributes/entries/atomic.json

@@ -0,0 +1,7 @@
+{
+    "$comment": "Distinct from `idempotent`, and the exactly-once machinery reads the difference literally: per-step journaling is safe inside a transaction PRECISELY because a rollback erases the journal's own entries too. A region that rolls nothing back has no such property, so it declares `idempotent` instead — borrowing this name there would let a journal's attestation relax collapse and record entries for effects that will re-run.",
+    "name": "atomic",
+    "requires": ["noSuspend"],
+    "value": { "type": "string", "minLength": 1 },
+    "description": "Effects inside are discarded together on failure, so a consumer recording them individually would record work a rollback erases."
+}