@telorun/sdk 0.77.0 → 0.79.0

package/src/invoke-step.ts

@@ -3,9 +3,26 @@ import {
   type CancellationToken,
   ERR_INVOKE_CANCELLED,
   type InvokeContext,
+  UNCANCELLABLE_CONTEXT,
+  createCancellationSource,
+  deriveContext,
   isCancellationError,
 } from "./cancellation.js";
 import { isAmbientContractErrorCode } from "./contract-errors.js";
+import {
+  durableHandleOf,
+  journalingSuppressed,
+  stepPath,
+  type DurableRunHandle,
+  type DurableTarget,
+} from "./durable-run.js";
+import {
+  SUSPENDING_BACKOFF_MS,
+  assertMaySuspend,
+  isSuspension,
+  parkRun,
+} from "./durable-suspension.js";
+import type { OpenZoneAttributes } from "./zone-attribute.js";
 import { tryParseDurationMs } from "./duration.js";
 import { InvokeError } from "./invoke-error.js";
 import type { KindRef, ScopeContext } from "./ref.js";
@@ -40,6 +57,26 @@ export interface InvokeStepRetry {
   jitter?: "none" | "full";
   /** DEPRECATED duration string (`"250ms"`, `"1s"`) — read as `initialDelay`. */
   delay?: string;
+  /**
+   * Error codes that end the loop immediately instead of consuming the budget.
+   *
+   * The leaf's built-in exclusions are the ones decidable WITHOUT judgement —
+   * cancellation, and the kernel's verdicts on the shape of the call. Whether a
+   * DOMAIN failure is worth re-attempting is not decidable here at all: an
+   * `ERR_PAYMENT_DECLINED` and an `ERR_UPSTREAM_TIMEOUT` are the same shape to
+   * this loop, and only the author knows that re-presenting a declined card
+   * changes nothing. Without this, every terminal domain failure is retried to
+   * exhaustion — which is not merely wasted time but, for a non-idempotent
+   * target, N extra attempts at a side effect.
+   *
+   * Named by CODE rather than by a predicate because a code is what crosses
+   * every boundary this has to survive: a manifest declares it, `catches:`
+   * already matches on it, and a relocating backend ships it as data. Both
+   * hosted engines express the same knob — Temporal's non-retryable error types,
+   * Restate's terminal-versus-retryable split — so a policy written here means
+   * the same thing wherever the step ends up executing.
+   */
+  nonRetryable?: string[];
 }
 
 /**
@@ -53,6 +90,29 @@ export interface InvokeStep {
   invoke: KindRef<Invocable> | Invocable;
   inputs?: Record<string, unknown>;
   retry?: InvokeStepRetry;
+  /**
+   * How long ONE attempt may take, in milliseconds. On elapse the dispatch is
+   * cancelled and the step fails `ERR_STEP_TIMEOUT`.
+   *
+   * Per attempt rather than for the whole loop, matching Temporal's
+   * start-to-close: a budget spanning the retries would make the last attempt's
+   * allowance depend on how slow the earlier ones were, so an author could not
+   * state what any single call is allowed to take. A whole-operation bound is a
+   * different thing and belongs to whatever owns the operation.
+   *
+   * It bounds the step rather than the target because the target does not know
+   * who is waiting: the same `Http.Request` is a 30-second batch call from one
+   * step and a 500ms call on a request path from another. It is also what a
+   * backend that chooses WHERE a step executes needs in order to choose —
+   * Temporal runs a short step as a local activity and a long one as an
+   * activity, which is not a decision a manifest should have to make.
+   *
+   * Enforced by cancellation, never by abandoning the call: the timeout source
+   * is linked to the caller's token and threaded into the dispatch, so a target
+   * that honours cancellation stops working rather than continuing unobserved
+   * past a deadline nobody is waiting on any more.
+   */
+  timeout?: number;
 }
 
 /** An inline flat invoke step on an Application's `targets`. Same as an
@@ -87,16 +147,30 @@ export type BootTarget =
 export interface InvokeStepContext {
   expandValue(value: any, context: Record<string, any>): any;
   invoke<TInputs>(kind: string, name: string, inputs: TInputs, options?: any): Promise<any>;
+  /** Open zones with what each declares about its contents — how the leaf and
+   *  the engine read the collapse rule. Optional so the structural context stays
+   *  satisfiable by a host with no zone machinery; ABSENT MEANS "no zone is
+   *  open", which is the direction that journals MORE rather than less, and so
+   *  the safe one. */
+  zoneAttributes?(ctx?: InvokeContext): readonly OpenZoneAttributes[];
   invokeResolved<TInputs>(
     kind: string,
     name: string,
     instance: ResourceInstance,
     inputs: TInputs,
+    /** Seeds the dispatch's invocation context, replacing the ambient — how a
+     *  step `timeout:` reaches the target it bounds. Optional so a leaf caller
+     *  that never sets one is unchanged. */
+    ctx?: InvokeContext,
   ): Promise<any>;
   /** Resolve a cross-module exported instance (`!ref Alias.name`) to its live instance.
    *  Optional — providers that pre-resolve cross-module refs before reaching the leaf
    *  (e.g. the boot-target runner) may omit it. */
   resolveImportedInstance?(alias: string, name: string): ResourceInstance | undefined;
+  /** Resolve a module-level sibling by name. Optional for the same reason the
+   *  one above is, and read here ONLY to recover a target's declaration site —
+   *  the dispatch itself still goes by name through the chokepoint. */
+  resolveLocalInstance?(name: string): ResourceInstance | undefined;
 }
 
 /**
@@ -127,6 +201,16 @@ export interface InvokeStepState {
    * invocation to forward.
    */
   invokeCtx?: InvokeContext;
+  /**
+   * This step's journal key, when the composer tracks one — see
+   * {@link stepPath}. Absent for a caller that assembled a step in code, and for
+   * the boot runner, whose targets are not a durable body.
+   *
+   * Supplied by the composer rather than derived here because a path is a
+   * property of the enclosing STRUCTURE (which branch, which loop turn, which
+   * fan-out element), and the leaf sees one step.
+   */
+  journalPath?: string;
 }
 
 /**
@@ -143,15 +227,148 @@ export async function executeInvokeStep(
   const cel = { steps: state.steps, ...state.cel };
   if (step.when !== undefined && !ctx.expandValue(step.when, cel)) return;
 
-  const inputs = ctx.expandValue(step.inputs ?? {}, cel) as Record<string, unknown>;
+  const rawHandle = durableHandleOf(state.invokeCtx);
+  // Inside a collapsed region the engine records NOTHING of its own: the region
+  // re-runs whole on resume, so per-step entries would describe work that is
+  // about to happen again. A resource inside it may still journal directly —
+  // which is what lets `Durable.Value` pin an impure evaluation there rather
+  // than be a prescription with nowhere to write.
+  const handle =
+    rawHandle && journalingSuppressed(ctx, state.invokeCtx, rawHandle) ? undefined : rawHandle;
+  const path = state.journalPath ?? step.name;
+
+  // The RESOLVED inputs are journaled, not re-derived. They are read from a CEL
+  // scope carrying live readings — `resources.<name>.status` is republished on
+  // every dispatch by design — so a fresh process can compute different
+  // arguments for the same step and hand them to a target the journal will then
+  // answer for, with no mismatch to detect.
+  const inputs = (handle
+    ? await handle.decide(stepPath(path, "inputs"), "inputs", () =>
+        ctx.expandValue(step.inputs ?? {}, cel),
+      )
+    : ctx.expandValue(step.inputs ?? {}, cel)) as Record<string, unknown>;
+
   const raw = step.invoke as unknown;
-  const result = await withStepRetry(step, state.invokeCtx, () =>
-    dispatch(raw, inputs, ctx, state),
-  );
+  // The dispatch carries THIS step's path, so anything it reaches that runs a
+  // step body of its own hangs those paths under this one rather than starting
+  // over at the root. Set only inside a durable run: outside one there is no
+  // path to carry, and deriving a context would be a rebuild for nothing.
+  // Derived from the RAW handle, not the collapse-suppressed one: collapse
+  // suppresses the engine's own per-step entries, never the journal. A
+  // `Durable.Value` or a parking kind inside a collapsed region still records
+  // directly, and it keys off this path — so dropping it here would give every
+  // such resource in the region ONE key inherited from an enclosing level.
+  const stepCtx =
+    rawHandle && state.invokeCtx
+      ? deriveContext(state.invokeCtx, { durablePath: path })
+      : state.invokeCtx;
+  const execute = () =>
+    withStepRetry(step, stepCtx, ctx, rawHandle, path, (attemptCtx) =>
+      withStepTimeout(step, attemptCtx, (dispatchCtx) =>
+        dispatch(raw, inputs, ctx, { ...state, invokeCtx: dispatchCtx }),
+      ),
+    );
+
+  // Retry and the timeout sit INSIDE the handed-over effect, not around it: a
+  // re-attempt is part of performing this step once, so a backend that ships the
+  // step elsewhere ships its policy with it rather than re-attempting a remote
+  // dispatch it does not own. This is also what keeps the attempt loop's own
+  // rule intact — the journal records the OUTCOME of the step, and a step whose
+  // third attempt succeeded completed once.
+  const result = handle
+    ? await handle.step(path, targetIdentityOf(raw, ctx, state), inputs, execute)
+    : await execute();
 
   state.steps[step.name] = { result };
 }
 
+/**
+ * The target's DECLARATION-SITE identity, for a backend that may execute the
+ * step somewhere the instance does not exist.
+ *
+ * Derived from the `!ref` identity the kernel stamps at Phase-5 injection, which
+ * is the only declaration-site fact a resolved target carries — instance
+ * identity is process-local by construction. Undefined when the step dispatches
+ * something with no stamp (a truly anonymous instance), which a local backend
+ * handles by simply running `execute` and a relocating one must refuse rather
+ * than guess.
+ */
+function targetIdentityOf(
+  raw: unknown,
+  ctx: InvokeStepContext,
+  state: InvokeStepState,
+): DurableTarget | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  // A pre-injected instance carries the stamp already.
+  const behind = getRefIdentity(raw as object) ? undefined : instanceBehind(raw, ctx, state);
+  const stamped = getRefIdentity(raw as object) ?? (behind && getRefIdentity(behind.instance));
+  const ref = raw as Partial<KindRef>;
+  const kind = stamped?.kind ?? (typeof ref.kind === "string" ? ref.kind : undefined);
+  const name = stamped?.name ?? (typeof ref.name === "string" ? ref.name : undefined);
+  if (!kind || !name) return undefined;
+  return {
+    kind,
+    name,
+    // Whether the name resolved inside a `with:` scope, which is knowable HERE
+    // and only here — the resolution is what answers it. The tuple identifying
+    // which scope RUN is not derivable yet, so this is what stops such a target
+    // being encoded as the module-level resource that shares its name.
+    ...(behind?.scoped ? { scoped: true as const } : {}),
+    // Carried through verbatim: the kernel derived it at the declaration site,
+    // which is the only place it is knowable, and a consumer that must name this
+    // target elsewhere has nothing else to name it with.
+    ...(stamped?.origin?.module === undefined ? {} : { module: stamped.origin.module }),
+    ...(stamped?.origin?.pointer === undefined ? {} : { pointer: stamped.origin.pointer }),
+  };
+}
+
+/**
+ * The live instance behind a step's `invoke:` REF, when this host can name one.
+ *
+ * A step's slot is not a Phase-5 injection site — it resolves at dispatch — so a
+ * step target arrives as a `{kind, name, alias?}` reference and carries no stamp
+ * of its own. Reading the instance's is what recovers the declaration site, and
+ * the resolution mirrors `dispatch`'s branches exactly so the identity describes
+ * the resource the step will actually reach.
+ *
+ * Reports whether the name resolved inside a `with:` SCOPE as well as what it
+ * resolved to, because that is a fact only the resolution knows and it changes
+ * what the identity means: a scoped name and a module-level one can be the same
+ * string and different resources.
+ *
+ * Best-effort by design: every resolver here is optional, and a host that
+ * supplies none yields an identity of kind and name alone — enough for a local
+ * backend, and refused by a relocating one rather than guessed at.
+ */
+function instanceBehind(
+  raw: object,
+  ctx: InvokeStepContext,
+  state: InvokeStepState,
+): { instance: object; scoped: boolean } | undefined {
+  const ref = raw as Partial<KindRef>;
+  if (typeof ref.name !== "string") return undefined;
+  try {
+    if (ref.alias && ref.alias !== "Self") {
+      const imported = ctx.resolveImportedInstance?.(ref.alias, ref.name) as object | undefined;
+      return imported && { instance: imported, scoped: false };
+    }
+    if (state.scope) {
+      // Scope-local FIRST, enclosing module as the fallback — the order
+      // `ScopeContext.getInstance` and the CEL `resources` layering already use,
+      // so what this reports a name to mean is what the dispatch will reach.
+      const scoped = state.scope.getInstance(ref.name) as unknown as object | undefined;
+      if (scoped) return { instance: scoped, scoped: true };
+    }
+    const local = ctx.resolveLocalInstance?.(ref.name) as object | undefined;
+    return local && { instance: local, scoped: false };
+  } catch {
+    // A resolver that throws is answering "not here", and the dispatch below is
+    // where that becomes an error with a message about the dispatch. Recovering
+    // provenance must not be the thing that reports it.
+    return undefined;
+  }
+}
+
 /**
  * Re-attempt a step's dispatch while its policy allows.
  *
@@ -185,45 +402,169 @@ export async function executeInvokeStep(
 async function withStepRetry<T>(
   step: InvokeStep,
   invokeCtx: InvokeContext | undefined,
-  dispatch: () => Promise<T>,
+  ctx: InvokeStepContext,
+  handle: DurableRunHandle | undefined,
+  path: string,
+  dispatch: (ctx: InvokeContext | undefined) => Promise<T>,
 ): Promise<T> {
   const policy = step.retry;
   const attempts = policy?.attempts ?? 0;
-  if (!policy || attempts <= 0) return dispatch();
+  if (!policy || attempts <= 0) return dispatch(invokeCtx);
 
-  const initial = policy.initialDelay ?? parseDuration(policy.delay) ?? 250;
-  const factor = policy.factor ?? 2;
-  const maxDelay = policy.maxDelay ?? 32_000;
   const jitter = policy.jitter ?? "full";
 
   for (let resend = 0; ; resend++) {
     try {
-      return await dispatch();
+      return await dispatch(invokeCtx);
     } catch (err) {
-      if (resend >= attempts || !isRetryable(err)) throw err;
-      const backoff = Math.min(maxDelay, initial * Math.pow(factor, resend));
-      await waitBeforeResend(
-        jitter === "full" ? Math.random() * backoff : backoff,
-        invokeCtx?.cancellation,
-        step,
-        err,
-      );
+      if (resend >= attempts || !isRetryable(err, policy.nonRetryable)) throw err;
+      // The UN-JITTERED backoff, which is a pure function of the declared policy
+      // and the attempt index — and which is therefore what the park decision
+      // below turns on. Deciding on the jittered value instead would put
+      // `Math.random()` on a control-flow branch inside a determinism contract:
+      // the same attempt could sleep on one pass and park on the next, for no
+      // reason a reader of the manifest could see. It would also make the static
+      // check unstateable, since the analyzer cannot know which way a coin
+      // landed. Jitter still does its whole job — spreading re-attempts — on the
+      // duration itself, in both branches.
+      const backoff = retryBackoffMs(policy, resend);
+      const delay = jitter === "full" ? Math.random() * backoff : backoff;
+
+      // A LONG backoff inside a durable run suspends rather than sleeps, and the
+      // attempt state is journaled with it. The obvious reading — only the
+      // outcome matters, so journal once — is wrong the moment a backoff
+      // suspends: a run that parks mid-retry and resumes in another process must
+      // know which attempt it was on, or it restarts the policy from zero and a
+      // three-attempt cap becomes unbounded.
+      //
+      // ONE DECISION PER ATTEMPT, holding when that attempt was due, is the
+      // whole mechanism. It needs nothing beyond `decide`: on resume the loop
+      // re-runs from attempt zero, each recorded attempt hands back a due time
+      // already in the past and is therefore consumed without waiting, and the
+      // first UNRECORDED attempt computes a fresh one and parks. The budget is
+      // preserved because the replayed attempts still count against it.
+      if (handle && backoff >= SUSPENDING_BACKOFF_MS) {
+        const attemptPath = stepPath(path, "retry", resend);
+        const dueAt = (await handle.decide(attemptPath, "value", () => Date.now() + delay)) as number;
+        if (Date.now() < dueAt) {
+          // Refused inside a region that promised nothing in it suspends. The
+          // check is here rather than at the policy, because a short backoff
+          // never suspends and rejecting one would forbid a retry that is
+          // perfectly safe in a lease.
+          assertMaySuspend(ctx, invokeCtx, { resource: step.name ?? path });
+          await parkRun(handle, { path: attemptPath, resource: step.name ?? path }, { at: dueAt });
+        }
+        continue;
+      }
+
+      await waitBeforeResend(delay, invokeCtx?.cancellation, step, err);
     }
   }
 }
 
+/**
+ * The backoff before attempt `resend + 1`, before jitter.
+ *
+ * ONE formula, exported because the analyzer needs the same number: it decides
+ * statically whether a step's declared policy would park inside a region that
+ * cannot be held open, and a second copy of exponential-backoff arithmetic in
+ * the analyzer would be a rule that drifts from the behaviour it describes the
+ * first time either side gains a knob.
+ *
+ * Jitter is deliberately NOT applied here. It belongs to the duration, not to
+ * the shape of the policy, and the two consumers want the shape: the runtime
+ * branches on it (see `withStepRetry`) and the analyzer reports on it.
+ *
+ * The `??` fallbacks are the floor for a caller that assembled a policy in code;
+ * a manifest gets its defaults from the schema.
+ */
+export function retryBackoffMs(policy: InvokeStepRetry, resend: number): number {
+  const initial = policy.initialDelay ?? parseDuration(policy.delay) ?? 250;
+  const factor = policy.factor ?? 2;
+  const maxDelay = policy.maxDelay ?? 32_000;
+  return Math.min(maxDelay, initial * Math.pow(factor, resend));
+}
+
 /** Kernel verdicts on the CALL rather than on the work, beyond the ambient
  *  contract set. A dispatch that cannot resolve its target is a manifest defect;
  *  re-issuing it re-resolves the same name against the same registry. */
 const UNRETRYABLE_CODES = new Set(["ERR_RESOURCE_NOT_FOUND", "ERR_RESOURCE_NOT_INVOKABLE"]);
 
-function isRetryable(err: unknown): boolean {
+function isRetryable(err: unknown, nonRetryable?: string[]): boolean {
   if (isCancellationError(err)) return false;
+  // A suspension is not a failure — it is the run leaving. Re-attempting it
+  // would park again under the same policy until the budget ran out, and the
+  // last attempt would propagate a park the earlier ones had already recorded.
+  if (isSuspension(err)) return false;
   const code = (err as { code?: unknown } | null | undefined)?.code;
   if (typeof code !== "string") return true;
+  // The author's own exclusions, checked beside the built-in ones rather than
+  // before or after them: they are the same question — is re-issuing this call
+  // capable of a different answer — asked about a domain failure the leaf has no
+  // way to classify. A step timeout is never in this set by default; whether a
+  // slow call is worth re-attempting is exactly the judgement an author makes.
+  if (nonRetryable?.includes(code)) return false;
   return !isAmbientContractErrorCode(code) && !UNRETRYABLE_CODES.has(code);
 }
 
+/**
+ * Bound ONE attempt, by cancellation rather than by abandonment.
+ *
+ * A `Promise.race` that simply rejects would leave the call running, holding its
+ * connection and eventually completing a side effect nobody is waiting on — the
+ * failure mode a timeout is usually adopted to prevent. So a timeout mints a
+ * cancellation source, LINKS it to the caller's token (or the caller's
+ * cancellation would stop propagating the moment a step declared a bound), and
+ * threads its context into the dispatch. A target that honours cancellation
+ * stops; one that does not is no worse off than before.
+ *
+ * The elapse is reported as `ERR_STEP_TIMEOUT` rather than as a cancellation,
+ * because the two want opposite follow-ups: a cancelled run was asked to stop,
+ * while a timed-out step is a target that is too slow for this call site — and
+ * `catches:` can only tell them apart if they carry different codes.
+ */
+async function withStepTimeout<T>(
+  step: InvokeStep,
+  invokeCtx: InvokeContext | undefined,
+  dispatch: (ctx: InvokeContext | undefined) => Promise<T>,
+): Promise<T> {
+  const ms = step.timeout;
+  if (ms === undefined || !(ms > 0)) return dispatch(invokeCtx);
+
+  const source = createCancellationSource();
+  const base = invokeCtx ?? UNCANCELLABLE_CONTEXT;
+  // Everything else on the context — zones, tracing, and whatever a later
+  // member adds — rides across unchanged. Rebuilding it as a literal here is
+  // the drop `deriveContext` exists to prevent.
+  const scoped = deriveContext(base, { cancellation: source.token });
+  const unlink = invokeCtx?.cancellation.onCancelled((reason) => source.cancel(reason));
+
+  let elapsed = false;
+  source.cancelAfter(ms);
+  const timedOut = source.token.onCancelled(() => {
+    if (!invokeCtx?.cancellation.isCancelled) elapsed = true;
+  });
+
+  try {
+    return await dispatch(scoped);
+  } catch (err) {
+    if (elapsed && isCancellationError(err)) {
+      throw new InvokeError(
+        "ERR_STEP_TIMEOUT",
+        `Step '${step.name}' exceeded its timeout of ${ms}ms and was cancelled`,
+        { step: step.name, timeout: ms },
+      );
+    }
+    throw err;
+  } finally {
+    timedOut();
+    unlink?.();
+    // Releases the pending deadline timer, so a step that finished early does
+    // not pin a timer alive until its bound elapses.
+    source.dispose();
+  }
+}
+
 /**
  * Wait out the backoff, or give up the moment the invocation is cancelled.
  *
@@ -299,6 +640,13 @@ async function dispatch(
 ): Promise<unknown> {
   let result: unknown;
 
+  // The context this attempt runs under: the step's timeout scope when it
+  // declares one, else whatever the composer forwarded. Threaded explicitly
+  // rather than installed as ambient because the SDK leaf has no ambient store
+  // to install into — that is one runtime's mechanism, and a second-language
+  // leaf has no `AsyncLocalStorage`.
+  const attemptCtx = state.invokeCtx;
+
   if (raw && typeof (raw as Invocable).invoke === "function") {
     // A pre-injected live instance (a `!ref` resolved at Phase 5). Route it
     // through the traced chokepoint using the identity the kernel stamped at
@@ -306,8 +654,14 @@ async function dispatch(
     // A truly anonymous instance (no stamp) falls back to a direct call.
     const identity = getRefIdentity(raw as object);
     result = identity
-      ? await ctx.invokeResolved(identity.kind, identity.name, raw as ResourceInstance, inputs)
-      : await (raw as Invocable).invoke(inputs);
+      ? await ctx.invokeResolved(
+          identity.kind,
+          identity.name,
+          raw as ResourceInstance,
+          inputs,
+          attemptCtx,
+        )
+      : await (raw as Invocable).invoke(inputs, attemptCtx);
   } else {
     const ref = raw as KindRef<Invocable>;
     if (ref.alias && ref.alias !== "Self") {
@@ -320,12 +674,12 @@ async function dispatch(
           `Cross-module reference '${ref.alias}.${ref.name}' did not resolve to an exported instance.`,
         );
       }
-      result = await ctx.invokeResolved(ref.kind, ref.name, instance, inputs);
+      result = await ctx.invokeResolved(ref.kind, ref.name, instance, inputs, attemptCtx);
     } else if (state.scope) {
       const instance = state.scope.getInstance(ref.name) as unknown as ResourceInstance;
-      result = await ctx.invokeResolved(ref.kind, ref.name, instance, inputs);
+      result = await ctx.invokeResolved(ref.kind, ref.name, instance, inputs, attemptCtx);
     } else {
-      result = await ctx.invoke(ref.kind, ref.name, inputs);
+      result = await ctx.invoke(ref.kind, ref.name, inputs, { ctx: attemptCtx });
     }
   }
   return result;

package/src/resource-context.ts

@@ -17,6 +17,7 @@ import { ResourceInstance } from "./resource-instance.js";
 import { ResourceManifest } from "./resource-manifest.js";
 import { RuntimeResource } from "./runtime-resource.js";
 import type { RuntimeSeam } from "./runtime-seam.js";
+import type { OpenZoneAttributes } from "./zone-attribute.js";
 
 export interface LoadOptions {
   /** When true, `${{ }}` templates are replaced with CompiledValue wrappers
@@ -150,6 +151,28 @@ export interface ResourceContext extends ControllerContext {
    *  one). No kind parameter: the provider's own per-instance map already
    *  discriminates — a zone this instance's owner did not open simply misses. */
   zonesFor(instance: ResourceInstance, ctx?: InvokeContext): readonly ZoneEntry[];
+  /**
+   * Every open zone with what it DECLARES about its contents, innermost first —
+   * the runtime half of `x-telo-provides-zone`'s attributes.
+   *
+   * Read off the declaring kind's schema, never off the entry: a
+   * {@link ZoneEntry} is three identities *because* that keeps it
+   * ABI-serializable and stops any module reading another's private state off
+   * the stack, and hanging attributes on it would trade that away for every
+   * zone. The kernel resolves the schema instead — the one place that lookup is
+   * already available — and hands the attributes over WITHOUT branching on a
+   * name, exactly as `readRefSlot` returns `use` without acting on it.
+   *
+   * The vocabulary is closed (`sdk/zone-attributes/`), which is what lets this
+   * be a typed record rather than a string-keyed bag. That is a readability
+   * gain and not a semantic one: interpreting an attribute is entirely the
+   * caller's — the step engine reads `atomic` to decide collapse, a parking kind
+   * reads `noSuspend` to refuse, and the kernel reads neither.
+   *
+   * Each value is the author's REASON, so a controller refusing on an attribute
+   * quotes the manifest's own sentence instead of inventing a generic message.
+   */
+  zoneAttributes(ctx?: InvokeContext): readonly OpenZoneAttributes[];
   /** The root context for runtime-driven inbound work (request, timer, queue
    *  message): inherits nothing from whatever ambient happens to be live at the
    *  registration site — no zones, no trace parent, no caller token. An inbound

package/src/resource-instance.ts

@@ -35,6 +35,27 @@ export const TEARDOWN_LAST = 1000;
 export interface RefIdentity {
   kind: string;
   name: string;
+  /**
+   * Where the instance was DECLARED, for a consumer that must name it somewhere
+   * the instance does not exist — a durable step shipped to another process.
+   *
+   * Optional because it is derived from the declaration and an instance stamped
+   * by a path that has none is still dispatchable; a consumer that genuinely
+   * needs it refuses rather than guessing (see `encodeDurableTarget`). Kept ON
+   * the identity rather than in a second table because it answers the same
+   * question the identity does — *which declaration is this* — one level more
+   * precisely.
+   */
+  origin?: RefOrigin;
+}
+
+/** The declaration site behind a live instance. `module` is the source of the
+ *  module that declared it, which is what tells two libraries' same-named
+ *  resources apart; `pointer` is set when the declaration is inline, and is a
+ *  JSON pointer into its declaring resource. */
+export interface RefOrigin {
+  module?: string;
+  pointer?: string;
 }
 
 /**
@@ -69,10 +90,19 @@ export const REF_IDENTITY: unique symbol = Symbol.for("telo.refIdentity");
 
 /** Stamp the resolved kind+name onto an injected instance. Idempotent — an
  *  instance has exactly one identity, so re-injection into other slots is a no-op. */
-export function stampRefIdentity(instance: object, kind: string, name: string): void {
+export function stampRefIdentity(
+  instance: object,
+  kind: string,
+  name: string,
+  origin?: RefOrigin,
+): void {
   if (!(REF_IDENTITY in instance)) {
     Object.defineProperty(instance, REF_IDENTITY, {
-      value: { kind, name } satisfies RefIdentity,
+      value: {
+        kind,
+        name,
+        ...(origin && (origin.module || origin.pointer) ? { origin } : {}),
+      } satisfies RefIdentity,
       enumerable: false,
       configurable: true,
       writable: false,