@telorun/sdk 0.77.0 → 0.80.0

package/dist/durable-run.js

@@ -0,0 +1,223 @@
+/**
+ * The durable-execution replay seam — `kernel/specs/durable-execution.md`.
+ *
+ * Durable execution is **journal plus deterministic replay**, and Telo can have
+ * it because of a property that fell out of `Run.Sequence`'s design: control
+ * flow is a finite, DECLARED set of CEL expressions over run state, not
+ * arbitrary code. So replay is re-running the step list while returning recorded
+ * values instead of computing them. No continuation capture.
+ *
+ * **What is shared is this narrow seam, not a portable engine vocabulary.** The
+ * temptation is to abstract durable execution itself — one surface every backend
+ * implements — and it fails the same way twice: the abstraction becomes the
+ * union of every engine's lifecycle model (identity policy, schedule overlap,
+ * cancel-versus-terminate, deployment pinning), and each backend still loses the
+ * half of its own model that did not generalize. Portability is close to
+ * worthless here — in-flight runs do not migrate between engines, the
+ * configuration shares nothing, and nobody switches durable engines twice.
+ *
+ * The real constraint is that **the step engine must not fork**. It lives in
+ * this package, which is symlinked into every controller bundle rather than
+ * inlined, so there is exactly one implementation however many backends exist.
+ * What still needs a seam is the other half — *whether and where a step
+ * executes* — and that is all this file is.
+ *
+ * **The kernel is a pure conduit**: it carries the handle on `InvokeContext` and
+ * never calls it, which is why the contract lives here rather than in the kernel
+ * — the split logging already makes between `Logger` / `RecordBuffer` and the
+ * `Telo.LogSink` abstract. The consequence is stated rather than implied: unlike
+ * `zones`, this member does NOT cross the ABI, so a second runtime threads a
+ * handle it owns.
+ */
+import { InvokeError } from "./invoke-error.js";
+import { VALUE_TYPES, VALUE_TYPE_BINDINGS } from "./value-type.js";
+/**
+ * Compose a step path — the journal's key, and the reason journaling lives in
+ * the step engine at all.
+ *
+ * A step path is the only naturally deterministic key available, and it survives
+ * CONCURRENCY where a per-run call ordinal would not: two branches of a
+ * concurrent fan-out interleave their dispatches, so an ordinal would number
+ * them differently on every run while their paths stay fixed. It is also what
+ * makes each branch of a fan-out an independently resumable subtree.
+ *
+ * Segments are joined with `/`; a repetition (a loop turn, an iteration element)
+ * qualifies its segment with `[index]`. Both are properties of the WRITTEN
+ * structure plus the run's own decisions, never of wall-clock order.
+ */
+export function stepPath(...segments) {
+    return segments
+        .map((s) => (typeof s === "number" ? `[${s}]` : s))
+        .join("/")
+        .replace(/\/\[/g, "[");
+}
+/** True when a run handle is ambient — the test the step engine makes before it
+ *  journals anything, so a non-durable sequence pays nothing. */
+export function durableHandleOf(ctx) {
+    return ctx?.durable;
+}
+/**
+ * What the step engine consults before journaling anything — the collapse rule,
+ * read off the ambient zone stack.
+ *
+ * > A region collapses to one entry when **re-running it is safe** — because its
+ * > effects are discarded together, or because re-running is a no-op.
+ *
+ * The rule has no fields in it, at either end. It used to be a caller-side
+ * `checkpoint: collapse` plus a callee-side `requireCheckpoints:` veto, which
+ * was wrong four ways at once: a boolean where every neighbouring annotation
+ * carries a reason; the opposite polarity from *everything journaled by
+ * default*, so forgetting to veto was silent; a veto available only on
+ * `Run.Sequence`, leaving a collapsed script or imported invocable unprotected;
+ * and a contradiction check to reconcile it with atomicity. Underneath all four,
+ * collapse was sold as a cost lever while being a CORRECTNESS decision — it
+ * silently converts exactly-once into at-least-once.
+ *
+ * A region with a property is a zone, so it is declared the way every other
+ * region property is. Nothing collapses a sequence because nothing wrapped it.
+ */
+export function collapsesJournalEntries(zones, handle) {
+    // Every region carrying one of the two attributes is resolved and REPORTED,
+    // including the ones walked past before a collapsing one was found: a
+    // transaction that attested its writes is an exactly-once region whether or
+    // not an idempotent zone further out collapses the whole thing, and reporting
+    // only the verdict would lose it.
+    const resolutions = [];
+    for (const zone of zones) {
+        // `idempotent` collapses FULL STOP: there is nothing for the journal to be
+        // inside, and re-running is a no-op either way.
+        if (zone.attributes.idempotent) {
+            resolutions.push({
+                zone: zone.kind,
+                attribute: "idempotent",
+                mode: "collapsed",
+                reason: zone.attributes.idempotent,
+            });
+            return { collapsed: true, resolutions };
+        }
+        // `atomic` collapses UNLESS the handle attests its own writes land inside
+        // that atomicity. This is not an override of the attribute; it is the
+        // attribute read correctly — *effects inside are discarded together*, so
+        // collapse follows only when the journal's writes are not among them. When
+        // they are, per-step journaling is consistent by construction AND strictly
+        // better: finer replay granularity, and no re-running a committed
+        // transaction.
+        if (zone.attributes.atomic) {
+            if (handle.writesInside(zone.entry)) {
+                resolutions.push({
+                    zone: zone.kind,
+                    attribute: "atomic",
+                    mode: "perStep",
+                    reason: zone.attributes.atomic,
+                    attestation: "writesInside",
+                });
+                continue;
+            }
+            resolutions.push({
+                zone: zone.kind,
+                attribute: "atomic",
+                mode: "collapsed",
+                reason: zone.attributes.atomic,
+            });
+            return { collapsed: true, resolutions };
+        }
+    }
+    return { collapsed: false, resolutions };
+}
+/**
+ * Should the step engine record nothing of its own right here?
+ *
+ * True inside a collapsed region, where per-step entries would describe work
+ * that is about to happen again — the region re-runs whole on resume, which is
+ * exactly what its author's attribute claims is safe.
+ *
+ * A host with no zone machinery reads as "no zone open", which journals MORE
+ * rather than less: the safe direction, since an unjournaled effect re-executes
+ * silently while a redundant entry costs a write.
+ */
+export function journalingSuppressed(ctx, invokeCtx, handle) {
+    const zones = ctx.zoneAttributes?.(invokeCtx);
+    if (!zones || zones.length === 0)
+        return false;
+    const verdict = collapsesJournalEntries(zones, handle);
+    for (const resolution of verdict.resolutions)
+        handle.noteZoneMode?.(resolution);
+    return verdict.collapsed;
+}
+/**
+ * Reject a value that cannot survive being recorded and read back.
+ *
+ * **`JSON.stringify` is not the test, and believing it was left the gate open.**
+ * A live handle has no enumerable state, so `JSON.stringify(stream)` returns
+ * `{}` and throws nothing — the one case the spec names first would have been
+ * recorded as an empty object and replayed as one, which is silent corruption
+ * rather than the loud failure §6 requires. The static half is deliberately only
+ * a warning ("the runtime is the gate"), so a gate that cannot see the case
+ * leaves it unenforced end to end.
+ *
+ * So a live value is detected STRUCTURALLY, by the value-type vocabulary's own
+ * binding table: an entry declaring `live: true` names a binding, and the host's
+ * table maps that binding to the constructor an assertion tests against. No type
+ * name is written here, so a live type added later is covered by its entry
+ * alone — the same reason the static rule reads the `live` field rather than
+ * naming `Telo.Stream`.
+ *
+ * Lives in the SDK rather than in a backend because it is a property of the
+ * CONTRACT (spec §6), not of one journal: a backend that skipped it would be
+ * non-conforming in a way nothing else could catch.
+ */
+export function assertJournalable(value, where) {
+    const live = findLiveValue(value, new Set());
+    if (live) {
+        throw new InvokeError("ERR_DURABLE_UNJOURNALABLE_VALUE", `Run '${where.run}': the value produced at '${where.path}' contains a ${live} handle, ` +
+            `which cannot be recorded. A live value is produced by CONSUMING it, so it exists ` +
+            `exactly once and a record of it would be a record of nothing — a replay would hand ` +
+            `the next step an empty value instead of the data. Read what you need out of it ` +
+            `inside the step and return that, or move the streaming work outside the durable body.`, { run: where.run, path: where.path, valueType: live });
+    }
+    try {
+        JSON.stringify(value);
+    }
+    catch (err) {
+        throw new InvokeError("ERR_DURABLE_UNJOURNALABLE_VALUE", `Run '${where.run}': the value produced at '${where.path}' cannot be serialized ` +
+            `(${err.message}). A durable step's result and every decision it reaches ` +
+            `must survive being written and read back.`, { run: where.run, path: where.path }, { cause: err });
+    }
+}
+/** The name of the first live value type found anywhere in `value`, or
+ *  undefined. Walks plain containers only — a class instance that is not a live
+ *  type is left to the serializer to judge, since `toJSON` may well make it
+ *  recordable. */
+function findLiveValue(value, seen) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    if (seen.has(value))
+        return undefined;
+    seen.add(value);
+    for (const entry of VALUE_TYPES.values()) {
+        if (!entry.live || !entry.binding)
+            continue;
+        const binding = VALUE_TYPE_BINDINGS[entry.binding];
+        if (binding && value instanceof binding.constructor)
+            return entry.name;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = findLiveValue(item, seen);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    // Only plain objects are descended into: walking an arbitrary instance's
+    // fields would report a live handle a `toJSON` was about to drop anyway.
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return undefined;
+    for (const item of Object.values(value)) {
+        const found = findLiveValue(item, seen);
+        if (found)
+            return found;
+    }
+    return undefined;
+}

package/dist/durable-suspension.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Suspension — the signal a parking kind raises, and the latch that catches a
+ * swallowed one. Slice 4 of `kernel/specs/durable-execution.md`.
+ *
+ * **Suspension is a distinct signal, not an error.** It unwinds the stack to the
+ * workflow boundary, so a `try:` step must not catch it, a composer's
+ * `catches:` must not map it, and a retry policy must not re-attempt it. Those
+ * three sites rethrow on {@link isSuspension} before they convert anything.
+ *
+ * **But naming the known swallowers is not a defence.** The signal passes
+ * through every controller between the parking kind and the workflow — HTTP
+ * handlers, agent tool loops, a cache view, and any third-party controller with
+ * a `catch (e)` in it. A swallowed suspension silently converts a park into a
+ * completed step and duplicates every effect after it, and a pure-conduit kernel
+ * cannot see that happen. Enumerating the swallowers is unbounded and would go
+ * stale on the next module.
+ *
+ * So it is **latched, not just thrown**: {@link parkRun} records the signal
+ * against the run handle at the moment it raises, and the workflow kind treats
+ * *an invocation that returned normally while a suspension is latched* as a hard
+ * error ({@link assertNotSwallowed}). Detection is O(1), needs no cooperation
+ * from the swallower, and turns an unbounded-surface silent corruption into one
+ * loud failure at the boundary that owns the run.
+ *
+ * **The latch lives here rather than on the backend's handle**, and the
+ * distinction is what makes it a guarantee: a backend that had to set it could
+ * forget to, and the failure of forgetting is the silent corruption this exists
+ * to catch. It is a `WeakMap` in the SDK — the one package with a single scope
+ * per process (`REALM_COLLAPSE_NAMES` symlinks it onto the kernel's copy), so
+ * the payload rule's "provider-private state hangs off an injected instance"
+ * does not bite: there is exactly one map however many controller bundles are
+ * loaded.
+ */
+import type { InvokeContext } from "./cancellation.js";
+import type { DurableRunHandle } from "./durable-run.js";
+/**
+ * The backoff above which a retry PARKS instead of sleeping.
+ *
+ * A threshold is unavoidable and so is stating where it came from. Below it,
+ * sleeping in process is cheaper than a park: a park is a journal write, a
+ * process exit and a poller pass, and paying that to save a few seconds of an
+ * idle timer is worse on both counts. Above it, holding a process open to wait
+ * is precisely what durability exists to stop — and the plan's own retry
+ * example (`delay: 10s`, three attempts) sits deliberately below it, while a
+ * policy backing off to minutes sits above.
+ *
+ * Shared with the analyzer, which decides statically whether a step's declared
+ * policy COULD suspend, so the check and the behaviour cannot disagree about
+ * where the line is.
+ */
+export declare const SUSPENDING_BACKOFF_MS = 30000;
+/** The code every suspension carries, so a runtime that only sees a shape can
+ *  still recognise one. */
+export declare const ERR_DURABLE_SUSPENDED = "ERR_DURABLE_SUSPENDED";
+/** Where a parked run is waiting for. Exactly one half is meaningful to a
+ *  backend at a time, but both may be present: an await with a deadline parks on
+ *  its token AND is due at a time. */
+export interface ParkUntil {
+    /** Epoch milliseconds at which the run becomes due. */
+    readonly at?: number;
+    /** The token a delivery must carry to wake this run. */
+    readonly token?: string;
+}
+/**
+ * The signal itself.
+ *
+ * An `Error` so it unwinds, and deliberately **not** an {@link InvokeError}: an
+ * `InvokeError` is the channel a `catches:` list maps by code, and a suspension
+ * that could be named there would be catchable by configuration — which is the
+ * corruption, spelled as a feature.
+ */
+export declare class DurableSuspension extends Error {
+    /** The run that parked. */
+    readonly runId: string;
+    /** The step path it parked at — the journal key its park is recorded under. */
+    readonly path: string;
+    /** The parking resource's `metadata.name`, so the diagnostic names what
+     *  waited rather than only where. */
+    readonly resource: string;
+    readonly until: ParkUntil;
+    readonly code = "ERR_DURABLE_SUSPENDED";
+    constructor(
+    /** The run that parked. */
+    runId: string, 
+    /** The step path it parked at — the journal key its park is recorded under. */
+    path: string, 
+    /** The parking resource's `metadata.name`, so the diagnostic names what
+     *  waited rather than only where. */
+    resource: string, until: ParkUntil);
+}
+/** Is this the suspension signal? Structural rather than `instanceof`, for the
+ *  same reason every other cross-boundary test here is: the SDK is one scope per
+ *  process today, and a runtime that threads a handle it owns should still be
+ *  recognised. */
+export declare function isSuspension(err: unknown): err is DurableSuspension;
+/**
+ * Park the run — the one way a parking kind suspends.
+ *
+ * Latches first, then asks the backend to record the park, then throws. Each of
+ * the three is load-bearing. Latching FIRST means a backend whose `park()`
+ * itself throws something else still leaves the evidence behind. Throwing here
+ * rather than trusting `park()`'s `Promise<never>` means a backend that returns
+ * — the one bug that would convert a wait into a completed step — is caught by
+ * the seam instead of by whatever ran next.
+ */
+export declare function parkRun(handle: DurableRunHandle, where: {
+    readonly path: string;
+    readonly resource: string;
+}, until: ParkUntil): Promise<never>;
+/** The suspension latched against this run, if one was raised during this
+ *  execution. */
+export declare function latchedSuspension(handle: DurableRunHandle): DurableSuspension | undefined;
+/**
+ * The workflow boundary's check: a body that returned normally while a
+ * suspension is latched swallowed one.
+ *
+ * Raised rather than repaired, because there is nothing to repair: every effect
+ * after the swallow already ran, un-parked and un-recorded, and the run's own
+ * record would say it completed. What is actionable is the pair of names — the
+ * resource that parked and the step path — since the swallower is somewhere
+ * between them.
+ */
+export declare function assertNotSwallowed(handle: DurableRunHandle): void;
+/**
+ * Refuse to park inside a zone that forbids it.
+ *
+ * The runtime half of `noSuspend` — one rule rather than an enumeration of
+ * forbidden kinds, so a parking kind added later is covered without touching
+ * anything here. The zone's own declared sentence is printed verbatim: it is the
+ * author's statement of what is being held open, and nothing generated says it
+ * better.
+ */
+export declare function assertMaySuspend(ctx: {
+    zoneAttributes?(ctx?: InvokeContext): readonly {
+        kind: string;
+        attributes: {
+            noSuspend?: string;
+        };
+    }[];
+}, invokeCtx: InvokeContext | undefined, where: {
+    readonly resource: string;
+}): void;
+//# sourceMappingURL=durable-suspension.d.ts.map

package/dist/durable-suspension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-suspension.d.ts","sourceRoot":"","sources":["../src/durable-suspension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGzD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;2BAC2B;AAC3B,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D;;sCAEsC;AACtC,MAAM,WAAW,SAAS;IACxB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAIxC,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB;yCACqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS;IAV3B,QAAQ,CAAC,IAAI,2BAAyB;;IAGpC,2BAA2B;IAClB,KAAK,EAAE,MAAM;IACtB,+EAA+E;IACtE,IAAI,EAAE,MAAM;IACrB;yCACqC;IAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS;CAQ5B;AAED;;;kBAGkB;AAClB,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAMnE;AAID;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC3D,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,KAAK,CAAC,CAKhB;AAED;iBACiB;AACjB,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,SAAS,CAEzF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAYjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE;IAAE,cAAc,CAAC,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,EAAE,CAAA;CAAE,EAC9G,SAAS,EAAE,aAAa,GAAG,SAAS,EACpC,KAAK,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnC,IAAI,CAWN"}

package/dist/durable-suspension.js

@@ -0,0 +1,153 @@
+/**
+ * Suspension — the signal a parking kind raises, and the latch that catches a
+ * swallowed one. Slice 4 of `kernel/specs/durable-execution.md`.
+ *
+ * **Suspension is a distinct signal, not an error.** It unwinds the stack to the
+ * workflow boundary, so a `try:` step must not catch it, a composer's
+ * `catches:` must not map it, and a retry policy must not re-attempt it. Those
+ * three sites rethrow on {@link isSuspension} before they convert anything.
+ *
+ * **But naming the known swallowers is not a defence.** The signal passes
+ * through every controller between the parking kind and the workflow — HTTP
+ * handlers, agent tool loops, a cache view, and any third-party controller with
+ * a `catch (e)` in it. A swallowed suspension silently converts a park into a
+ * completed step and duplicates every effect after it, and a pure-conduit kernel
+ * cannot see that happen. Enumerating the swallowers is unbounded and would go
+ * stale on the next module.
+ *
+ * So it is **latched, not just thrown**: {@link parkRun} records the signal
+ * against the run handle at the moment it raises, and the workflow kind treats
+ * *an invocation that returned normally while a suspension is latched* as a hard
+ * error ({@link assertNotSwallowed}). Detection is O(1), needs no cooperation
+ * from the swallower, and turns an unbounded-surface silent corruption into one
+ * loud failure at the boundary that owns the run.
+ *
+ * **The latch lives here rather than on the backend's handle**, and the
+ * distinction is what makes it a guarantee: a backend that had to set it could
+ * forget to, and the failure of forgetting is the silent corruption this exists
+ * to catch. It is a `WeakMap` in the SDK — the one package with a single scope
+ * per process (`REALM_COLLAPSE_NAMES` symlinks it onto the kernel's copy), so
+ * the payload rule's "provider-private state hangs off an injected instance"
+ * does not bite: there is exactly one map however many controller bundles are
+ * loaded.
+ */
+import { InvokeError } from "./invoke-error.js";
+/**
+ * The backoff above which a retry PARKS instead of sleeping.
+ *
+ * A threshold is unavoidable and so is stating where it came from. Below it,
+ * sleeping in process is cheaper than a park: a park is a journal write, a
+ * process exit and a poller pass, and paying that to save a few seconds of an
+ * idle timer is worse on both counts. Above it, holding a process open to wait
+ * is precisely what durability exists to stop — and the plan's own retry
+ * example (`delay: 10s`, three attempts) sits deliberately below it, while a
+ * policy backing off to minutes sits above.
+ *
+ * Shared with the analyzer, which decides statically whether a step's declared
+ * policy COULD suspend, so the check and the behaviour cannot disagree about
+ * where the line is.
+ */
+export const SUSPENDING_BACKOFF_MS = 30_000;
+/** The code every suspension carries, so a runtime that only sees a shape can
+ *  still recognise one. */
+export const ERR_DURABLE_SUSPENDED = "ERR_DURABLE_SUSPENDED";
+/**
+ * The signal itself.
+ *
+ * An `Error` so it unwinds, and deliberately **not** an {@link InvokeError}: an
+ * `InvokeError` is the channel a `catches:` list maps by code, and a suspension
+ * that could be named there would be catchable by configuration — which is the
+ * corruption, spelled as a feature.
+ */
+export class DurableSuspension extends Error {
+    runId;
+    path;
+    resource;
+    until;
+    code = ERR_DURABLE_SUSPENDED;
+    constructor(
+    /** The run that parked. */
+    runId, 
+    /** The step path it parked at — the journal key its park is recorded under. */
+    path, 
+    /** The parking resource's `metadata.name`, so the diagnostic names what
+     *  waited rather than only where. */
+    resource, until) {
+        super(`Run '${runId}' parked at '${path}' (${resource}). This is a suspension signal, not a ` +
+            `failure: it must reach the workflow that owns the run.`);
+        this.runId = runId;
+        this.path = path;
+        this.resource = resource;
+        this.until = until;
+        this.name = "DurableSuspension";
+    }
+}
+/** Is this the suspension signal? Structural rather than `instanceof`, for the
+ *  same reason every other cross-boundary test here is: the SDK is one scope per
+ *  process today, and a runtime that threads a handle it owns should still be
+ *  recognised. */
+export function isSuspension(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === ERR_DURABLE_SUSPENDED);
+}
+const LATCHED = new WeakMap();
+/**
+ * Park the run — the one way a parking kind suspends.
+ *
+ * Latches first, then asks the backend to record the park, then throws. Each of
+ * the three is load-bearing. Latching FIRST means a backend whose `park()`
+ * itself throws something else still leaves the evidence behind. Throwing here
+ * rather than trusting `park()`'s `Promise<never>` means a backend that returns
+ * — the one bug that would convert a wait into a completed step — is caught by
+ * the seam instead of by whatever ran next.
+ */
+export async function parkRun(handle, where, until) {
+    const signal = new DurableSuspension(handle.runId, where.path, where.resource, until);
+    LATCHED.set(handle, signal);
+    await handle.park(where, until);
+    throw signal;
+}
+/** The suspension latched against this run, if one was raised during this
+ *  execution. */
+export function latchedSuspension(handle) {
+    return LATCHED.get(handle);
+}
+/**
+ * The workflow boundary's check: a body that returned normally while a
+ * suspension is latched swallowed one.
+ *
+ * Raised rather than repaired, because there is nothing to repair: every effect
+ * after the swallow already ran, un-parked and un-recorded, and the run's own
+ * record would say it completed. What is actionable is the pair of names — the
+ * resource that parked and the step path — since the swallower is somewhere
+ * between them.
+ */
+export function assertNotSwallowed(handle) {
+    const signal = LATCHED.get(handle);
+    if (!signal)
+        return;
+    throw new InvokeError("ERR_DURABLE_SUSPENSION_SWALLOWED", `Run '${signal.runId}': '${signal.resource}' parked the run at step '${signal.path}', but ` +
+        `the body returned normally — something between them caught the suspension signal and ` +
+        `continued. Every step after the park has now run outside the journal, and the run would ` +
+        `have been recorded as completed. A controller in that path has a 'catch' that swallows ` +
+        `unknown errors; it must rethrow anything it did not recognise.`, { run: signal.runId, path: signal.path, resource: signal.resource });
+}
+/**
+ * Refuse to park inside a zone that forbids it.
+ *
+ * The runtime half of `noSuspend` — one rule rather than an enumeration of
+ * forbidden kinds, so a parking kind added later is covered without touching
+ * anything here. The zone's own declared sentence is printed verbatim: it is the
+ * author's statement of what is being held open, and nothing generated says it
+ * better.
+ */
+export function assertMaySuspend(ctx, invokeCtx, where) {
+    for (const zone of ctx.zoneAttributes?.(invokeCtx) ?? []) {
+        const reason = zone.attributes.noSuspend;
+        if (!reason)
+            continue;
+        throw new InvokeError("ERR_DURABLE_SUSPEND_FORBIDDEN", `'${where.resource}' would park the run, but it is inside a ${zone.kind} zone that ` +
+            `cannot be held open across a suspension: ${reason}`, { resource: where.resource, zone: zone.kind, reason });
+    }
+}

package/dist/durable-target-encoding.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The wire form of a {@link DurableTarget} — spec §5.3.
+ *
+ * Written in the slice where something first sends one across a process
+ * boundary, and not before: a normative format frozen with no consumer is the
+ * failure the sequencing rule exists to prevent. What crosses first is a child
+ * kernel, which is a real boundary — it shares no instance graph with its
+ * parent, so nothing about a target can survive by accident.
+ *
+ * **JSON, not a URI.** A journal entry already carries its target as JSON, and a
+ * second serialization vocabulary for one value is a second thing to keep
+ * agreeing. What this adds over `JSON.stringify` is what a FORMAT has to add:
+ * a canonical key order, so two runtimes producing the same identity produce the
+ * same bytes and an equality check needs no parser; a version tag, so a later
+ * form is refused rather than misread; and a stated set of required fields per
+ * form, so an incomplete identity is refused at the encoder rather than
+ * resolving to the wrong resource at the far end.
+ *
+ * **Three forms, discriminated by shape rather than by a tag.** Which one a
+ * target is follows from which fields it carries — `scope` makes it scoped,
+ * `pointer` makes it inline, neither makes it module-level — and the encoder
+ * refuses a value carrying both, since that is not a fourth form but a
+ * contradiction.
+ */
+import type { DurableTarget } from "./durable-run.js";
+/** Bumped only for a change a previous reader would MISREAD. A new optional
+ *  field a reader can ignore is not one; a change to what an existing field
+ *  means is. */
+export declare const DURABLE_TARGET_ENCODING_VERSION = 1;
+/**
+ * Encode a target for transport.
+ *
+ * Refuses rather than guesses. An identity missing what its form requires would
+ * decode at the far end into a resource that is merely *similar*, and a step
+ * executed against the wrong resource is the one failure durable execution must
+ * never produce quietly — so an incomplete target is an error at the sender,
+ * where the manifest that produced it is still in reach.
+ */
+export declare function encodeDurableTarget(target: DurableTarget): string;
+/**
+ * Decode a target received from another process.
+ *
+ * A version this reader does not know is REFUSED, never read as far as it
+ * understands: the fields it recognizes may mean something else in a form it has
+ * never seen, and resolving anyway is how a step gets executed against a
+ * resource nobody named.
+ */
+export declare function decodeDurableTarget(encoded: string): DurableTarget;
+//# sourceMappingURL=durable-target-encoding.d.ts.map

package/dist/durable-target-encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-target-encoding.d.ts","sourceRoot":"","sources":["../src/durable-target-encoding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD;;gBAEgB;AAChB,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAiBjD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAiEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAiDlE"}