more real imports (#9243)

refs: #9149

## Description

Replace more of the `@typedef` "import" with actual `@import`. Should
help with docs generation.

### Security Considerations

<!-- Does this change introduce new assumptions or dependencies that, if
violated, could introduce security vulnerabilities? How does this PR
change the boundaries between mutually-suspicious components? What new
authorities are introduced by this change, perhaps by new API calls?
-->

### Scaling Considerations

<!-- Does this change require or encourage significant increase in
consumption of CPU cycles, RAM, on-chain storage, message exchanges, or
other scarce resources? If so, can that be prevented or mitigated? -->

### Documentation Considerations

<!-- Give our docs folks some hints about what needs to be described to
downstream users.

Backwards compatibility: what happens to existing data or deployments
when this code is shipped? Do we need to instruct users to do something
to upgrade their saved data? If there is no upgrade path possible, how
bad will that be for users?

-->

### Testing Considerations

<!-- Every PR should of course come with tests of its own functionality.
What additional tests are still needed beyond those unit tests? How does
this affect CI, other test automation, or the testnet?
-->

### Upgrade Considerations

<!-- What aspects of this PR are relevant to upgrading live production
systems, and how should they be addressed? -->

packages/agoric-cli/src/commands/inter.js

@@ -33,16 +33,16 @@ const bidInvitationShape = harden({
   callPipe: [['makeBidInvitation', M.any()]],
 });
 
-/** @typedef {import('@agoric/vats/tools/board-utils.js').VBankAssetDetail } AssetDescriptor */
-/** @typedef {import('@agoric/smart-wallet/src/smartWallet.js').TryExitOfferAction } TryExitOfferAction */
+/** @import {VBankAssetDetail} from '@agoric/vats/tools/board-utils.js'; */
+/** @import {TryExitOfferAction} from '@agoric/smart-wallet/src/smartWallet.js'; */
 /** @import {OfferSpec as BidSpec} from '@agoric/inter-protocol/src/auction/auctionBook.js' */
 /** @import {ScheduleNotification} from '@agoric/inter-protocol/src/auction/scheduler.js' */
 /** @import {BookDataNotification} from '@agoric/inter-protocol/src/auction/auctionBook.js' */
 
 /**
  * Format amounts, prices etc. based on brand board Ids, displayInfo
  *
- * @param {AssetDescriptor[]} assets
+ * @param {VBankAssetDetail[]} assets
  */
 const makeFormatters = assets => {
   const r4 = x => Math.round(x * 10_000) / 10_000;
@@ -138,7 +138,7 @@ const coerceBid = (offerStatus, agoricNames, warn) => {
  *
  * @param {import('@agoric/smart-wallet/src/offers.js').OfferStatus &
  *         { offerArgs: BidSpec}} bid
- * @param {import('../lib/format.js').AssetDescriptor[]} assets
+ * @param {VBankAssetDetail[]} assets
  */
 export const fmtBid = (bid, assets) => {
   const fmt = makeFormatters(assets);

packages/agoric-cli/src/lib/format.js

@@ -3,6 +3,7 @@
 import { makeBoardRemote } from '@agoric/vats/tools/board-utils.js';
 
 /** @import {BoardRemote} from '@agoric/vats/tools/board-utils.js' */
+/** @import {VBankAssetDetail} from '@agoric/vats/tools/board-utils.js'; */
 
 /**
  * Like @endo/nat but coerces
@@ -26,7 +27,7 @@ export const Natural = str => {
  */
 export const bigintReplacer = (k, v) => (typeof v === 'bigint' ? `${v}` : v);
 
-/** @type {Partial<import('@agoric/vats/tools/board-utils.js').VBankAssetDetail>} */
+/** @type {Partial<VBankAssetDetail>} */
 // eslint-disable-next-line no-unused-vars
 const exampleAsset = {
   brand: makeBoardRemote({ boardId: 'board0425', iface: 'Alleged: BLD brand' }),
@@ -35,10 +36,8 @@ const exampleAsset = {
   proposedName: 'Agoric staking token',
 };
 
-/** @typedef {import('@agoric/vats/tools/board-utils.js').VBankAssetDetail } AssetDescriptor */
-
 /**
- * @param {AssetDescriptor[]} assets
+ * @param {VBankAssetDetail[]} assets
  * @returns {(a: Amount & { brand: BoardRemote }) => [string | null, number | any[]]}
  */
 export const makeAmountFormatter = assets => amt => {
@@ -90,7 +89,7 @@ export const asBoardRemote = x => {
  * Summarize the balances array as user-facing informative tuples
  *
  * @param {import('@agoric/smart-wallet/src/smartWallet.js').CurrentWalletRecord['purses']} purses
- * @param {AssetDescriptor[]} assets
+ * @param {VBankAssetDetail[]} assets
  */
 export const purseBalanceTuples = (purses, assets) => {
   const fmt = makeAmountFormatter(assets);

packages/agoric-cli/test/test-inter-cli.js

@@ -14,7 +14,7 @@ const { entries } = Object;
 
 /**
  * @import { Command } from 'commander';
- * @import { BoardRemote } from '@agoric/vats/tools/board-utils.js';
+ * @import { BoardRemote, VBankAssetDetail } from '@agoric/vats/tools/board-utils.js';
  */
 
 /**
@@ -39,7 +39,7 @@ const agoricNames = harden({
     auctioneer: makeBoardRemote({ boardId: 'board434', iface: 'Instance' }),
   },
 
-  /** @type {Record<string,import('../src/lib/format.js').AssetDescriptor>} */
+  /** @type {Record<string, VBankAssetDetail>} */
   vbankAsset: {
     ubld: {
       denom: 'ubld',

packages/cosmic-swingset/src/launch-chain.js

@@ -10,6 +10,8 @@ import anylogger from 'anylogger';
 import { E } from '@endo/far';
 import bundleSource from '@endo/bundle-source';
 
+/** @import {RunPolicy} from '@agoric/swingset-vat' */
+
 import {
   buildMailbox,
   buildMailboxStateMap,
@@ -242,7 +244,7 @@ export async function buildSwingset(
 }
 
 /**
- * @typedef {import('@agoric/swingset-vat').RunPolicy & {
+ * @typedef {RunPolicy & {
  *   shouldRun(): boolean;
  *   remainingBeans(): bigint | undefined;
  *   totalBeans(): bigint;

packages/governance/src/types.js

@@ -1,5 +1,7 @@
 export {};
 
+/** @import {ContractStartFunction} from '@agoric/zoe/src/zoeService/utils.js' */
+
 /**
  * @typedef { 'unranked' | 'order' | 'plurality' } ChoiceMethod
  * * UNRANKED: "unranked voting" means that the voter specifies some number of
@@ -696,7 +698,7 @@ export {};
  */
 
 /**
- * @typedef {import('@agoric/zoe/src/zoeService/utils.js').ContractStartFunction
+ * @typedef {ContractStartFunction
  * & ((zcf?: any, pa?: any, baggage?: any) => ERef<{creatorFacet: GovernedCreatorFacet<{}>, publicFacet: GovernedPublicFacet<{}>}>)} GovernableStartFn
  */
 

packages/inter-protocol/src/proposals/econ-behaviors.js

@@ -13,6 +13,8 @@ import { makeGovernedTerms as makeGovernedATerms } from '../auction/params.js';
 import { makeReserveTerms } from '../reserve/params.js';
 import { makeGovernedTerms as makeGovernedVFTerms } from '../vaultFactory/params.js';
 
+/** @import {StartedInstanceKit} from '@agoric/zoe/src/zoeService/utils.js' */
+
 const trace = makeTracer('RunEconBehaviors', true);
 
 export const SECONDS_PER_MINUTE = 60n;
@@ -67,12 +69,12 @@ export const SECONDS_PER_WEEK = 7n * SECONDS_PER_DAY;
  */
 
 /**
- * @typedef {import('@agoric/zoe/src/zoeService/utils.js').StartedInstanceKit<
+ * @typedef {StartedInstanceKit<
  *   import('../econCommitteeCharter.js')['start']
  * >} EconCharterStartResult
  */
 /**
- * @typedef {import('@agoric/zoe/src/zoeService/utils.js').StartedInstanceKit<
+ * @typedef {StartedInstanceKit<
  *   import('@agoric/governance/src/committee.js')['start']
  * >} CommitteeStartResult
  */

packages/inter-protocol/test/auction/test-scheduler.js

@@ -22,7 +22,10 @@ import {
   setUpInstallations,
 } from './tools.js';
 
-/** @import {TimerService} from '@agoric/time' */
+/**
+ * @import {TimerService} from '@agoric/time';
+ * @import {AuctionParams} from '../../src/auction/params.js';
+ */
 
 test('schedule start to finish', async t => {
   const { zcf, zoe } = await setupZCFTest();
@@ -50,7 +53,7 @@ test('schedule start to finish', async t => {
     StartFrequency: 10n,
     PriceLockPeriod: 5n,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -273,7 +276,7 @@ test('lowest >= starting', async t => {
     LowestRate: 110n,
     StartingRate: 105n,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -324,7 +327,7 @@ test('zero time for auction', async t => {
     AuctionStartDelay: 1n,
     PriceLockPeriod: 1n,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -370,7 +373,7 @@ test('discountStep 0', async t => {
     ...defaultParams,
     DiscountStep: 0n,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -417,7 +420,7 @@ test('discountStep larger than starting rate', async t => {
     StartingRate: 10100n,
     DiscountStep: 10500n,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -463,7 +466,7 @@ test('start Freq 0', async t => {
     ...defaultParams,
     StartFrequency: 0n,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -510,7 +513,7 @@ test('delay > freq', async t => {
     AuctionStartDelay: 40n,
     StartFrequency: 20n,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -558,7 +561,7 @@ test('lockPeriod > freq', async t => {
     StartFrequency: 3600n,
     AuctionStartDelay: 500n,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -613,7 +616,7 @@ test('duration = freq', async t => {
     LowestRate: 40n,
     DiscountStep: 10n,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -692,7 +695,7 @@ test('change Schedule', async t => {
   // start hourly, request 6 steps down every 10 minutes, so duration would be
   // 1 hour. Instead, cut the auction short.
 
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   defaultParams = {
     ...defaultParams,
     PriceLockPeriod: lockPeriodT,
@@ -704,7 +707,7 @@ test('change Schedule', async t => {
     DiscountStep: 10n,
   };
 
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -885,7 +888,7 @@ test('change Schedule late', async t => {
   // start hourly, request 6 steps down every 10 minutes, so duration would be
   // 1 hour. Instead, cut the auction short.
 
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   defaultParams = {
     ...defaultParams,
     PriceLockPeriod: lockPeriodT,
@@ -897,7 +900,7 @@ test('change Schedule late', async t => {
     DiscountStep: 10n,
   };
 
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),
@@ -1116,7 +1119,7 @@ test('schedule anomalies', async t => {
     AuctionStartDelay: delay,
     PriceLockPeriod: lock,
   };
-  /** @type {import('../../src/auction/params.js').AuctionParams} */
+  /** @type {AuctionParams} */
   // @ts-expect-error ignore missing values for test
   const paramValues = objectMap(
     makeAuctioneerParams(defaultParams),

packages/internal/src/callback.js

@@ -4,6 +4,7 @@ import { isObject, isPassableSymbol } from '@endo/marshal';
 import { getInterfaceMethodKeys } from '@endo/patterns';
 
 /** @import { ERef } from '@endo/far' */
+/** @import { Callback, SyncCallback } from './types.js' */
 
 const { Fail, quote: q } = assert;
 
@@ -20,16 +21,6 @@ const ownKeys =
  * @typedef {(...args: Parameters<ReturnType<prepareAttenuator>>) => import('@endo/exo').Farable<T>} MakeAttenuator
  */
 
-/**
- * @template {(...args: unknown[]) => any} I
- * @typedef {import('./types.js').Callback<I>} Callback
- */
-
-/**
- * @template {(...args: unknown[]) => any} I
- * @typedef {import('./types.js').SyncCallback<I>} SyncCallback
- */
-
 /**
  * @param {unknown} key
  * @returns {key is PropertyKey} FIXME: should be just `PropertyKey` but TS

packages/internal/src/lib-chainStorage.js

@@ -132,7 +132,7 @@ export const prepareChainStorageNode = zone => {
   /**
    * Create a storage node for a given backing storage interface and path.
    *
-   * @param {import('./callback.js').Callback<(message: StorageMessage) => any>} messenger a callback
+   * @param {import('./types.js').Callback<(message: StorageMessage) => any>} messenger a callback
    * for sending a storageMessage object to the storage implementation
    * (cf. golang/cosmos/x/vstorage/vstorage.go)
    * @param {string} path
@@ -147,7 +147,7 @@ export const prepareChainStorageNode = zone => {
     'ChainStorageNode',
     ChainStorageNodeI,
     /**
-     * @param {import('./callback.js').Callback<(message: StorageMessage) => any>} messenger
+     * @param {import('./types.js').Callback<(message: StorageMessage) => any>} messenger
      * @param {string} path
      * @param {object} [options]
      * @param {boolean} [options.sequence]