@telorun/sdk 0.75.0 → 0.79.0

package/src/durable-suspension.ts

@@ -0,0 +1,188 @@
+/**
+ * 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";
+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";
+
+/** 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 class DurableSuspension extends Error {
+  readonly code = ERR_DURABLE_SUSPENDED;
+
+  constructor(
+    /** 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,
+  ) {
+    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.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: unknown): err is DurableSuspension {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as { code?: unknown }).code === ERR_DURABLE_SUSPENDED
+  );
+}
+
+const LATCHED = new WeakMap<DurableRunHandle, 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 async function parkRun(
+  handle: DurableRunHandle,
+  where: { readonly path: string; readonly resource: string },
+  until: ParkUntil,
+): Promise<never> {
+  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: DurableRunHandle): DurableSuspension | undefined {
+  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: DurableRunHandle): void {
+  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: { zoneAttributes?(ctx?: InvokeContext): readonly { kind: string; attributes: { noSuspend?: string } }[] },
+  invokeCtx: InvokeContext | undefined,
+  where: { readonly resource: string },
+): void {
+  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/src/durable-target-encoding.ts

@@ -0,0 +1,181 @@
+/**
+ * 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";
+import { InvokeError } from "./invoke-error.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 const DURABLE_TARGET_ENCODING_VERSION = 1;
+
+/**
+ * Canonical key order: `v`, `kind`, `name`, `module`, `pointer`, `scope`, and
+ * inside `scope`, `owner`, `site`, `stepPath`.
+ *
+ * Fixed rather than left to whichever code path built the target, because two
+ * paths producing the same identity must produce the same bytes — that is what
+ * lets a recipient compare, log and key on the encoded form without decoding it
+ * first. Enforced by BUILDING the payload in this order and letting
+ * `JSON.stringify` follow insertion order, not by passing these as its replacer
+ * array: a replacer array filters keys at EVERY depth, so the nested scope keys
+ * are absent from the top-level list and a scoped target would encode with an
+ * empty `scope` — the identity's whole distinguishing half, dropped silently.
+ */
+const SCOPE_KEY_ORDER = ["owner", "site", "stepPath"] as const;
+
+/**
+ * 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 function encodeDurableTarget(target: DurableTarget): string {
+  if (!target.kind || !target.name) {
+    throw new InvokeError(
+      "ERR_DURABLE_TARGET_UNENCODABLE",
+      `A step target must carry both a kind and a name to cross a process boundary; ` +
+        `got kind='${target.kind ?? ""}' name='${target.name ?? ""}'.`,
+      { target },
+    );
+  }
+  if (target.pointer !== undefined && (target.scoped || target.scope !== undefined)) {
+    throw new InvokeError(
+      "ERR_DURABLE_TARGET_UNENCODABLE",
+      `A step target is declared one way: at module level, inside a 'with:' scope, or ` +
+        `inline. This one carries both a scope and a pointer, which describes no ` +
+        `declaration site.`,
+      { target },
+    );
+  }
+  // The module is what disambiguates two libraries that each declare a `store`,
+  // and a recipient resolving without it would pick whichever it saw first. It
+  // is required for every form that leaves the process, and optional only on the
+  // in-process interface, where an entry written before it was recorded must
+  // still replay.
+  if (!target.module) {
+    throw new InvokeError(
+      "ERR_DURABLE_TARGET_UNENCODABLE",
+      `Step target ${target.kind} '${target.name}' carries no declaring module, so a ` +
+        `recipient could not tell it from a same-named resource in another module.`,
+      { target },
+    );
+  }
+  // A SCOPED target must carry its tuple, and the check is on `scoped` rather
+  // than on the presence of `scope` — otherwise a scoped target whose tuple
+  // could not be derived would pass here as module-level, which is precisely the
+  // misresolution this refusal exists to prevent: at the far end that identity
+  // names a DIFFERENT resource that merely shares the name.
+  if (target.scoped || target.scope !== undefined) {
+    for (const key of SCOPE_KEY_ORDER) {
+      if (target.scope?.[key]) continue;
+      throw new InvokeError(
+        "ERR_DURABLE_TARGET_UNENCODABLE",
+        `Step target ${target.kind} '${target.name}' is declared inside a 'with:' scope ` +
+          `but records no ${key}. A scoped instance is distinguished by its scope RUN, so ` +
+          `an identity missing that names every run of the scope at once.`,
+        { target },
+      );
+    }
+  }
+  const payload: Record<string, unknown> = {
+    v: DURABLE_TARGET_ENCODING_VERSION,
+    kind: target.kind,
+    name: target.name,
+    module: target.module,
+    ...(target.pointer === undefined ? {} : { pointer: target.pointer }),
+    ...(target.scope === undefined
+      ? {}
+      : {
+          scope: {
+            owner: target.scope.owner,
+            site: target.scope.site,
+            stepPath: target.scope.stepPath,
+          },
+        }),
+  };
+  return JSON.stringify(payload);
+}
+
+/**
+ * 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 function decodeDurableTarget(encoded: string): DurableTarget {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(encoded);
+  } catch (err) {
+    throw new InvokeError(
+      "ERR_DURABLE_TARGET_UNDECODABLE",
+      `A step target arrived that is not valid JSON: ${(err as Error).message}`,
+      { encoded },
+      { cause: err },
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new InvokeError(
+      "ERR_DURABLE_TARGET_UNDECODABLE",
+      `A step target arrived that is not an object.`,
+      { encoded },
+    );
+  }
+  const raw = parsed as Record<string, unknown>;
+  if (raw.v !== DURABLE_TARGET_ENCODING_VERSION) {
+    throw new InvokeError(
+      "ERR_DURABLE_TARGET_UNDECODABLE",
+      `A step target arrived in encoding version ${String(raw.v)}, and this runtime reads ` +
+        `version ${DURABLE_TARGET_ENCODING_VERSION}. Reading the fields it recognizes would ` +
+        `risk resolving a resource nobody named.`,
+      { encoded },
+    );
+  }
+  if (typeof raw.kind !== "string" || typeof raw.name !== "string" || typeof raw.module !== "string") {
+    throw new InvokeError(
+      "ERR_DURABLE_TARGET_UNDECODABLE",
+      `A step target arrived without a kind, a name or a module.`,
+      { encoded },
+    );
+  }
+  const scope = raw.scope as Record<string, unknown> | undefined;
+  return {
+    kind: raw.kind,
+    name: raw.name,
+    module: raw.module,
+    ...(typeof raw.pointer === "string" ? { pointer: raw.pointer } : {}),
+    ...(scope &&
+    typeof scope.owner === "string" &&
+    typeof scope.site === "string" &&
+    typeof scope.stepPath === "string"
+      ? { scope: { owner: scope.owner, site: scope.site, stepPath: scope.stepPath } }
+      : {}),
+  };
+}

package/src/duration.ts

@@ -1,6 +1,6 @@
 /**
  * Duration parsing — the shared time helper for controllers. Telo writes human
- * durations (`250ms`, `2s`, `1.5m`, `1h`) in manifests for timers, TTLs,
+ * durations (`250ms`, `2s`, `1.5m`, `1h`, `30d`) in manifests for timers, TTLs,
  * windows, connect timeouts, backoff, and so on; this is the single place that
  * turns one into a millisecond count. Consumers own their own error UX:
  * `tryParseDurationMs` returns `null` on a bad string so a caller can throw its
@@ -10,8 +10,8 @@
  */
 import { RuntimeError } from "./types.js";
 
-const DURATION_PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)$/;
-const UNIT_MS = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 } as const;
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/;
+const UNIT_MS = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
 
 /** Parse a duration string to milliseconds, or `null` if it is not a valid
  *  duration. Lets the caller own the error message and error type. */
@@ -21,7 +21,7 @@ export function tryParseDurationMs(value: string): number | null {
   return Number(match[1]) * UNIT_MS[match[2] as keyof typeof UNIT_MS];
 }
 
-/** Parse a duration string (`300s`, `5m`, `1h`, `50ms`) to milliseconds. An
+/** Parse a duration string (`300s`, `5m`, `1h`, `30d`, `50ms`) to milliseconds. An
  *  `undefined` value yields `fallback` (default `0`) for optional fields; an
  *  invalid string throws a plain `Error`. */
 export function parseDurationMs(value: string | undefined, fallback = 0): number {
@@ -30,7 +30,7 @@ export function parseDurationMs(value: string | undefined, fallback = 0): number
   if (ms === null) {
     throw new RuntimeError(
       "ERR_INVALID_VALUE",
-      `Invalid duration ${JSON.stringify(value)}; use a number with a unit, e.g. "250ms", "2s", "1.5m", "1h".`,
+      `Invalid duration ${JSON.stringify(value)}; use a number with a unit, e.g. "250ms", "2s", "1.5m", "1h", "30d".`,
     );
   }
   return ms;

package/src/evaluation-context.ts

@@ -115,6 +115,23 @@ export interface EvaluationContext {
 
   preInitHook?: PreInitHook;
 
+  /**
+   * The manifest a name was DECLARED with, resolved scope-local first and then
+   * up the enclosing chain; `alias` routes into that import's exported
+   * instances. Undefined when the name resolves to nothing.
+   *
+   * A DECLARATION, not an instance — nothing here yields one. It is what a
+   * contract typed from a referenced declaration reads
+   * (`x-telo-schema-projection-from`), which the pending-resource queue cannot
+   * answer because it has drained by the time a contract is bound.
+   *
+   * Optional, like every other kernel-supplied hook on this interface
+   * (`getDefinition?`, `preInitHook?`) and for the same reason: a third-party
+   * implementation must keep compiling. Absent reads as "no declaration in
+   * scope", which leaves a projected slot as its author wrote it.
+   */
+  resolveDeclaredManifest?(name: string, alias?: string): ResourceManifest | undefined;
+
   /** Looks up a registered resource definition by fully-qualified kind.
    *  Set by the kernel; used for declared-throw-union checks. */
   getDefinition?: (kind: string) => ResourceDefinition | undefined;

package/src/index.ts

@@ -5,6 +5,7 @@ export * from "./capabilities/invokable.js";
 export * from "./ref.js";
 export * from "./type-schema-ref.js";
 export * from "./invoke-step.js";
+export * from "./step-engine.js";
 export * from "./dispatch-invoke-ref.js";
 export * from "./capabilities/provider.js";
 export * from "./capabilities/runnable.js";
@@ -34,5 +35,8 @@ export * from "./runtime-event.js";
 export * from "./runtime-resource.js";
 export * from "./stream.js";
 export * from "./types.js";
+export * from "./durable-run.js";
+export * from "./durable-suspension.js";
+export * from "./durable-target-encoding.js";
 export * from "./value-type.js";
-
+export * from "./zone-attribute.js";