@telorun/sdk 0.77.0 → 0.80.0

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