@telorun/sdk 0.83.0 → 0.86.0

package/dist/module-context.d.ts

@@ -42,7 +42,36 @@ export interface ModuleContext extends EvaluationContext {
     } | undefined;
     /** Resolve a cross-module exported-instance reference `Alias.name` to its live instance. */
     resolveImportedInstance(alias: string, name: string): ResourceInstance | undefined;
-    getInstance(name: string): unknown;
+    /**
+     * Resolve a sibling by NAME.
+     *
+     * A resolution taken while the module is still initializing is RECORDED,
+     * because a caller that resolves during `init()` may hold what it gets, and
+     * nothing in the manifest says so: a name passed here is invisible to the
+     * reference walk that builds the dependency edges, so a host rebuilding that
+     * resource cannot know this caller is holding it. Recording is what makes the
+     * host fall back to rebuilding the whole context instead of silently leaving
+     * a holder pointing at a dead instance.
+     *
+     * A resolution taken after initialization is not recorded: it re-resolves per
+     * dispatch, so there is nothing to hold and nothing to invalidate.
+     *
+     * Prefer an `x-telo-ref` slot, which declares the edge and costs the caller
+     * nothing at run time — the kernel injects the live instance before `init()`.
+     * This is for the case a slot cannot express, and its cost is that the
+     * resource it names can no longer be rebuilt on its own.
+     *
+     * `declaredBy` is for the one caller that has a declared slot behind it and
+     * only wants the lookup: the SDK's own `!ref` resolution, for a reference that
+     * reached a controller as a raw sentinel instead of being injected. Passing
+     * the resolved ref suppresses the record, because the edge is in the manifest
+     * already. There is deliberately no second METHOD for this — a public door
+     * whose documentation asks you not to use it is one that gets used.
+     */
+    getInstance(name: string, declaredBy?: {
+        kind: string;
+        name: string;
+    }): unknown;
     getInvocable<TInput = Record<string, any>, TOutput = any>(name: string): Invocable<TInput, TOutput>;
     resolveKind(kind: string): string;
     runTargets(ctx?: InvokeContext): Promise<void>;

package/dist/module-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-context.d.ts","sourceRoot":"","sources":["../src/module-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5C,4EAA4E;IAC5E,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAClD,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACrC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACnD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI,CAAC;IAChE,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAAC;IAEpD;;8FAE0F;IAC1F,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IACrF;4EACwE;IACxE,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChE;;+FAE2F;IAC3F,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC5F,4FAA4F;IAC5F,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACnF,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,YAAY,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,EACtD,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,UAAU,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD"}
+{"version":3,"file":"module-context.d.ts","sourceRoot":"","sources":["../src/module-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5C,4EAA4E;IAC5E,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAClD,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACrC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACnD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI,CAAC;IAChE,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAAC;IAEpD;;8FAE0F;IAC1F,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IACrF;4EACwE;IACxE,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAChE;;+FAE2F;IAC3F,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC5F,4FAA4F;IAC5F,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACnF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;IAChF,YAAY,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,EACtD,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,UAAU,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD"}

package/dist/resolve-ref-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-ref-instance.d.ts","sourceRoot":"","sources":["../src/resolve-ref-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;;;;;;;OAOG;IACH,oBAAoB,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,SAAS,IAAI,CAAC,EAC7C,QAAQ,EAAE,MAAM,MAAM,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,CAiCH"}
+{"version":3,"file":"resolve-ref-instance.d.ts","sourceRoot":"","sources":["../src/resolve-ref-instance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;;;;;;;OAOG;IACH,oBAAoB,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,SAAS,IAAI,CAAC,EAC7C,QAAQ,EAAE,MAAM,MAAM,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,CAqCH"}

package/dist/resolve-ref-instance.js

@@ -47,7 +47,11 @@ export function resolveRefInstance(value, ctx, guard, describe, expects) {
     // it is an alias that crosses no import boundary.
     const instance = ref.alias && ref.alias !== "Self"
         ? ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name)
-        : (ctx.resolveLocalInstance?.(ref.name) ?? ctx.moduleContext.getInstance(ref.name));
+        : // The DECLARED door: this name came out of a ref slot, so the edge is
+            // already in the manifest and recording it would mark the target
+            // unreconcilable on the strength of a reference the host can see.
+            (ctx.resolveLocalInstance?.(ref.name) ??
+                ctx.moduleContext.getInstance(ref.name, { kind: ref.kind, name: ref.name }));
     if (!guard(instance)) {
         const label = ref.alias ? `${ref.alias}.${ref.name}` : ref.name;
         throw new RuntimeError("ERR_REF_UNRESOLVED", `${describe()} reference '${label}' did not resolve to a ${target}` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sdk",
-  "version": "0.83.0",
+  "version": "0.86.0",
   "description": "Telo SDK - Public API for Telo module authors.",
   "keywords": [
     "telo",

package/src/module-context.ts

@@ -43,7 +43,33 @@ export interface ModuleContext extends EvaluationContext {
   resolveImportedRef(alias: string, name: string): { kind: string; name: string } | undefined;
   /** Resolve a cross-module exported-instance reference `Alias.name` to its live instance. */
   resolveImportedInstance(alias: string, name: string): ResourceInstance | undefined;
-  getInstance(name: string): unknown;
+  /**
+   * Resolve a sibling by NAME.
+   *
+   * A resolution taken while the module is still initializing is RECORDED,
+   * because a caller that resolves during `init()` may hold what it gets, and
+   * nothing in the manifest says so: a name passed here is invisible to the
+   * reference walk that builds the dependency edges, so a host rebuilding that
+   * resource cannot know this caller is holding it. Recording is what makes the
+   * host fall back to rebuilding the whole context instead of silently leaving
+   * a holder pointing at a dead instance.
+   *
+   * A resolution taken after initialization is not recorded: it re-resolves per
+   * dispatch, so there is nothing to hold and nothing to invalidate.
+   *
+   * Prefer an `x-telo-ref` slot, which declares the edge and costs the caller
+   * nothing at run time — the kernel injects the live instance before `init()`.
+   * This is for the case a slot cannot express, and its cost is that the
+   * resource it names can no longer be rebuilt on its own.
+   *
+   * `declaredBy` is for the one caller that has a declared slot behind it and
+   * only wants the lookup: the SDK's own `!ref` resolution, for a reference that
+   * reached a controller as a raw sentinel instead of being injected. Passing
+   * the resolved ref suppresses the record, because the edge is in the manifest
+   * already. There is deliberately no second METHOD for this — a public door
+   * whose documentation asks you not to use it is one that gets used.
+   */
+  getInstance(name: string, declaredBy?: { kind: string; name: string }): unknown;
   getInvocable<TInput = Record<string, any>, TOutput = any>(
     name: string,
   ): Invocable<TInput, TOutput>;

package/src/resolve-ref-instance.ts

@@ -77,7 +77,11 @@ export function resolveRefInstance<T>(
   const instance =
     ref.alias && ref.alias !== "Self"
       ? ctx.moduleContext.resolveImportedInstance(ref.alias, ref.name)
-      : (ctx.resolveLocalInstance?.(ref.name) ?? ctx.moduleContext.getInstance(ref.name));
+      : // The DECLARED door: this name came out of a ref slot, so the edge is
+        // already in the manifest and recording it would mark the target
+        // unreconcilable on the strength of a reference the host can see.
+        (ctx.resolveLocalInstance?.(ref.name) ??
+          ctx.moduleContext.getInstance(ref.name, { kind: ref.kind as string, name: ref.name }));
 
   if (!guard(instance)) {
     const label = ref.alias ? `${ref.alias}.${ref.name}` : ref.name;