normalize types-ambient (#9309)

refs: #9305

## Description

While working on #9305 I was slowed down by the `types.js` files that
were really ambients.

This makes all `types.js` that aren't modules into `types-ambient.js`. 

The ambients for `zoe/tools` I ditched by making them explicit exports,
to continue supporting that part of the package API that the `prepack`
rename was doing.

### 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/oracle.js

@@ -19,6 +19,8 @@ import {
 } from '../lib/wallet.js';
 import { bigintReplacer } from '../lib/format.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 // XXX support other decimal places
 const COSMOS_UNIT = 1_000_000n;
 const scaleDecimals = num => BigInt(num * Number(COSMOS_UNIT));

packages/assert/exported.js

@@ -1 +1 @@
-import './src/types.js';
+import './src/types-ambient.js';

packages/assert/src/assert.js

@@ -18,7 +18,7 @@
 // is a record of a failed attempt to remove '.types'.
 // To satisfy CI, not only do we need to keep the file,
 // but we need to import it here as well.
-/// <reference path="./types.js" />
+/// <reference path="./types-ambient.js" />
 
 const { freeze } = Object;
 

packages/base-zone/src/types.js

@@ -1,6 +1,9 @@
 // eslint-disable-next-line no-unused-vars
 import { makeExo, defineExoClass, defineExoClassKit } from '@endo/exo';
 
+// Ensure this is a module.
+export {};
+
 /** @typedef {'exoClass' | 'exoClassKit' | 'exo' | 'store' | 'zone'} KeyCategories */
 /** @typedef {Record<KeyCategories, (label: string) => string[]>} KeyMakers */
 

packages/inter-protocol/exported.js

@@ -1,2 +1,2 @@
-import './src/psm/types.js';
-import './src/vaultFactory/types.js';
+import './src/psm/types-ambient.js';
+import './src/vaultFactory/types-ambient.js';

packages/inter-protocol/src/auction/auctionBook.js

@@ -29,6 +29,11 @@ import {
   priceFrom,
 } from './util.js';
 
+/**
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
+
 const { Fail } = assert;
 const { makeEmpty } = AmountMath;
 
@@ -90,8 +95,6 @@ export const makeOfferSpecShape = (bidBrand, collateralBrand) => {
   );
 };
 
-/** @import {Baggage} from '@agoric/vat-data' */
-
 /**
  * @typedef {object} BookDataNotification
  * @property {Ratio | null} startPrice identifies the priceAuthority and price

packages/inter-protocol/src/auction/auctioneer.js

@@ -35,7 +35,10 @@ import { auctioneerParamTypes } from './params.js';
 import { makeScheduler } from './scheduler.js';
 import { AuctionState } from './util.js';
 
-/** @import {Baggage} from '@agoric/vat-data' */
+/**
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
 
 const { Fail, quote: q } = assert;
 const { add, multiply } = natSafeMath;

packages/inter-protocol/src/auction/params.js

@@ -6,8 +6,11 @@ import {
 import { TimeMath, RelativeTimeRecordShape } from '@agoric/time';
 import { M } from '@agoric/store';
 
-/** @import {AsyncSpecTuple} from '@agoric/governance/src/contractGovernance/typedParamManager.js' */
-/** @import {SyncSpecTuple} from '@agoric/governance/src/contractGovernance/typedParamManager.js' */
+/**
+ * @import {AsyncSpecTuple} from '@agoric/governance/src/contractGovernance/typedParamManager.js';
+ * @import {SyncSpecTuple} from '@agoric/governance/src/contractGovernance/typedParamManager.js';
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
 
 // TODO duplicated with zoe/src/TypeGuards.js
 export const InvitationShape = M.remotable('Invitation');

packages/inter-protocol/src/auction/util.js

@@ -7,6 +7,8 @@ import {
 } from '@agoric/zoe/src/contractSupport/index.js';
 import { Far } from '@endo/marshal';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 /**
  * Constants for Auction State.
  *

packages/inter-protocol/src/contractSupport.js

@@ -4,6 +4,8 @@ import { AmountMath } from '@agoric/ertp';
 import { M } from '@agoric/store';
 import { makeRatioFromAmounts } from '@agoric/zoe/src/contractSupport/index.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 const { Fail, quote: q } = assert;
 
 export const amountPattern = harden({ brand: M.remotable(), value: M.any() });

packages/inter-protocol/src/price/fluxAggregatorKit.js

@@ -18,6 +18,8 @@ import { Far } from '@endo/marshal';
 import { prepareOracleAdminKit } from './priceOracleKit.js';
 import { prepareRoundsManagerKit } from './roundsManager.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 const trace = makeTracer('FlxAgg', true);
 
 export const INVITATION_MAKERS_DESC = 'oracle invitation';

packages/inter-protocol/src/price/roundsManager.js

@@ -14,10 +14,10 @@ import { UnguardedHelperI } from '@agoric/internal/src/typeGuards.js';
 
 const { add, subtract, multiply, floorDivide, ceilDivide, isGTE } = natSafeMath;
 
-/** @import {OracleStatus} from './priceOracleKit.js' */
 /**
- * @import {Timestamp} from '@agoric/time'
- * @import {TimerService} from '@agoric/time'
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ * @import {Timestamp, TimerService} from '@agoric/time'
+ * @import {OracleStatus} from './priceOracleKit.js'
  */
 
 /** @type {string} */

packages/inter-protocol/src/vaultFactory/liquidation.js

@@ -17,6 +17,7 @@ const trace = makeTracer('LIQ');
 /** @import {TimerWaker} from '@agoric/time' */
 /** @import {CancelToken} from '@agoric/time' */
 /** @import {RelativeTimeRecord} from '@agoric/time' */
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
 
 const makeCancelToken = makeCancelTokenMaker('liq');
 

packages/inter-protocol/src/vaultFactory/math.js

@@ -16,6 +16,8 @@ import {
 import { priceFrom } from '../auction/util.js';
 import { addSubtract } from '../contractSupport.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 /**
  * Calculate the minimum collateralization given the liquidation margin and the
  * "padding" from that liquidation threshold.

packages/inter-protocol/src/vaultFactory/params.js

@@ -1,6 +1,6 @@
 // @jessie-check
 
-/// <reference path="./types.js" />
+/// <reference path="./types-ambient.js" />
 
 import {
   CONTRACT_ELECTORATE,
@@ -14,6 +14,8 @@ import { provideDurableMapStore } from '@agoric/vat-data';
 import { subtractRatios } from '@agoric/zoe/src/contractSupport/ratio.js';
 import { amountPattern, ratioPattern } from '../contractSupport.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 export const CHARGING_PERIOD_KEY = 'ChargingPeriod';
 export const RECORDING_PERIOD_KEY = 'RecordingPeriod';
 

packages/inter-protocol/src/vaultFactory/proceeds.js

@@ -9,6 +9,8 @@ import {
 import { quoteAsRatio, subtractToEmpty } from '../contractSupport.js';
 import { liquidationResults } from './liquidation.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 /**
  * @typedef {{
  *   overage: Amount<'nat'>;

packages/inter-protocol/src/vaultFactory/storeUtils.js

@@ -5,6 +5,8 @@
  * API supports them.
  */
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 // XXX importing these that are declared to be used only for testing
 // until @agoric/store supports composite keys
 import { makeDecodePassable, makeEncodePassable } from '@endo/marshal';

packages/inter-protocol/src/vaultFactory/types.js → packages/inter-protocol/src/vaultFactory/types-ambient.js

@@ -76,7 +76,7 @@
  * @typedef {object} GetVaultParams
  * @property {() => Ratio} getLiquidationMargin
  * @property {() => Ratio} getMintFee
- * @property {() => Promise<PriceQuote>} getCollateralQuote
+ * @property {() => Promise<import('@agoric/zoe/tools/types.js').PriceQuote>} getCollateralQuote
  * @property {() => Ratio} getInterestRate - The annual interest rate on a debt
  *   position
  * @property {() => RelativeTime} getChargingPeriod - The period (in seconds) at

packages/inter-protocol/src/vaultFactory/vaultFactory.js

@@ -32,6 +32,8 @@ import { InvitationShape } from '../auction/params.js';
 import { SHORTFALL_INVITATION_KEY, vaultDirectorParamTypes } from './params.js';
 import { provideDirector } from './vaultDirector.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 const trace = makeTracer('VF', true);
 
 /**

packages/inter-protocol/src/vaultFactory/vaultManager.js

@@ -64,6 +64,11 @@ import { makePrioritizedVaults } from './prioritizedVaults.js';
 import { Phase, prepareVault } from './vault.js';
 import { calculateDistributionPlan } from './proceeds.js';
 
+/**
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
+
 const { details: X, Fail, quote: q } = assert;
 
 const trace = makeTracer('VM');

packages/inter-protocol/test/psm/test-psm.js

@@ -1,7 +1,7 @@
 import { test as anyTest } from '@agoric/zoe/tools/prepare-test-env-ava.js';
 
 import '@agoric/zoe/exported.js';
-import '../../src/vaultFactory/types.js';
+import '../../src/vaultFactory/types-ambient.js';
 
 import { AmountMath, makeIssuerKit } from '@agoric/ertp';
 import { split } from '@agoric/ertp/src/legacy-payment-helpers.js';

packages/inter-protocol/test/vaultFactory/driver.js

@@ -25,7 +25,7 @@ import {
   startVaultFactory,
 } from '../../src/proposals/econ-behaviors.js';
 import { startEconomicCommittee } from '../../src/proposals/startEconCommittee.js';
-import '../../src/vaultFactory/types.js';
+import '../../src/vaultFactory/types-ambient.js';
 import {
   installPuppetGovernance,
   setupBootstrap,

packages/inter-protocol/test/vaultFactory/test-collatRatio.js

@@ -8,6 +8,8 @@ import { makeRatioFromAmounts } from '@agoric/zoe/src/contractSupport/index.js';
 import { normalizedCollRatio } from '../../src/vaultFactory/storeUtils.js';
 import { withAmountUtils } from '../supports.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 export const mockBrand = Far('brand');
 
 const makeFakeQuote = (amountIn, amountOut) => {

packages/inter-protocol/test/vaultFactory/test-math.js

@@ -7,7 +7,10 @@ import {
 } from '../../src/vaultFactory/math.js';
 import { withAmountUtils } from '../supports.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 const stable = withAmountUtils(makeIssuerKit('Stable'));
+
 const aeth = withAmountUtils(makeIssuerKit('Aeth'));
 
 //#region maxDebtForVaults

packages/inter-protocol/test/vaultFactory/test-proceeds.js

@@ -7,6 +7,8 @@ import { makeRatio } from '@agoric/zoe/src/contractSupport/index.js';
 import { calculateDistributionPlan } from '../../src/vaultFactory/proceeds.js';
 import { withAmountUtils } from '../supports.js';
 
+/** @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js'; */
+
 const debt = withAmountUtils(makeIssuerKit('IST'));
 const coll = withAmountUtils(makeIssuerKit('aEth'));
 

packages/inter-protocol/test/vaultFactory/test-replacePriceAuthority.js

@@ -32,7 +32,7 @@ import {
   startVaultFactory,
 } from '../../src/proposals/econ-behaviors.js';
 
-import '../../src/vaultFactory/types.js';
+import '../../src/vaultFactory/types-ambient.js';
 import { defaultParamValues } from './vaultFactoryUtils.js';
 
 /** @import {VaultFactoryContract as VFC} from '../../src/vaultFactory/vaultFactory.js' */

packages/inter-protocol/test/vaultFactory/test-storage.js

@@ -7,7 +7,7 @@ import { E } from '@endo/eventual-send';
 import { assertTopicPathData, subscriptionKey } from '../supports.js';
 import { makeDriverContext, makeManagerDriver } from './driver.js';
 
-import '../../src/vaultFactory/types.js';
+import '../../src/vaultFactory/types-ambient.js';
 
 /** @typedef {import('./driver.js').DriverContext & {}} Context */
 /** @type {import('ava').TestFn<Context>} */

packages/inter-protocol/test/vaultFactory/test-vaultFactory.js

@@ -25,7 +25,7 @@ import { deeplyFulfilled } from '@endo/marshal';
 import { calculateCurrentDebt } from '../../src/interest-math.js';
 import { SECONDS_PER_YEAR } from '../../src/interest.js';
 import { startVaultFactory } from '../../src/proposals/econ-behaviors.js';
-import '../../src/vaultFactory/types.js';
+import '../../src/vaultFactory/types-ambient.js';
 import {
   metricsTracker,
   reserveInitialState,
@@ -40,7 +40,10 @@ import {
   setupElectorateReserveAndAuction,
 } from './vaultFactoryUtils.js';
 
-/** @import {VaultFactoryContract as VFC} from '../../src/vaultFactory/vaultFactory.js' */
+/**
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ * @import {VaultFactoryContract as VFC} from '../../src/vaultFactory/vaultFactory.js'
+ */
 
 /**
  * @typedef {Record<string, any> & {

packages/inter-protocol/test/vaultFactory/test-vaultLiquidation.js

@@ -25,7 +25,7 @@ import {
   SECONDS_PER_WEEK as ONE_WEEK,
   startVaultFactory,
 } from '../../src/proposals/econ-behaviors.js';
-import '../../src/vaultFactory/types.js';
+import '../../src/vaultFactory/types-ambient.js';
 import {
   reserveInitialState,
   subscriptionTracker,

packages/inter-protocol/test/vaultFactory/vaultFactoryUtils.js

@@ -14,7 +14,7 @@ import {
   setupReserve,
   startAuctioneer,
 } from '../../src/proposals/econ-behaviors.js';
-import '../../src/vaultFactory/types.js';
+import '../../src/vaultFactory/types-ambient.js';
 import {
   installPuppetGovernance,
   produceInstallations,

packages/vats/src/priceAuthorityRegistry.js

@@ -10,6 +10,11 @@ import { E } from '@endo/far';
 import { Far } from '@endo/marshal';
 import { PriceAuthorityI } from '@agoric/zoe/src/contractSupport/priceAuthority.js';
 
+/**
+ * @import {Baggage} from '@agoric/vat-data';
+ * @import {MutableQuote, PriceAuthority, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
+
 const { Fail } = assert;
 
 /**

packages/wallet/api/exported.js

@@ -1 +1 @@
-import './src/types.js';
+import './src/types-ambient.js';

packages/wallet/api/test/test-getPursesNotifier.js

@@ -11,7 +11,7 @@ import {
 } from '@agoric/vats/src/nameHub.js';
 import { makeWalletRoot } from '../src/lib-wallet.js';
 
-import '../src/types.js';
+import '../src/types-ambient.js';
 
 const mixinMyAddress = prepareMixinMyAddress(makeHeapZone());
 

packages/wallet/api/test/test-lib-wallet.js

@@ -21,7 +21,7 @@ import { resolve as importMetaResolve } from 'import-meta-resolve';
 import { makeHeapZone } from '@agoric/zone';
 import { makeWalletRoot } from '../src/lib-wallet.js';
 
-import '../src/types.js';
+import '../src/types-ambient.js';
 
 const ZOE_INVITE_PURSE_PETNAME = 'Default Zoe invite purse';
 

packages/zoe/exported.js

@@ -5,7 +5,6 @@ import './src/zoeService/types-ambient.js';
 import './src/contractSupport/types-ambient.js';
 import './src/contracts/exported.js';
 import './src/types-ambient.js';
-import './tools/types-ambient.js';
 import '@agoric/notifier/exported.js';
 import '@agoric/ertp/exported.js';
 import '@agoric/store/exported.js';

packages/zoe/package.json

@@ -10,8 +10,8 @@
   "scripts": {
     "build": "yarn build:bundles",
     "build:bundles": "node scripts/build-bundles.js",
-    "prepack": "echo \"export {}; \" | cat - tools/types-ambient.js > tools/types.js && tsc --build tsconfig.build.json",
-    "postpack": "git clean -f '*.d.ts*' tools/types.js",
+    "prepack": "tsc --build tsconfig.build.json",
+    "postpack": "git clean -f '*.d.ts*'",
     "test": "ava --verbose",
     "test:c8": "c8 $C8_OPTIONS ava --config=ava-nesm.config.js",
     "test:unit": "ava 'test/unitTests/**/test-*.js' -T 1m --verbose",

packages/zoe/src/contractSupport/priceAuthority.js

@@ -8,6 +8,10 @@ import { makeTracer } from '@agoric/internal';
 import { TimestampShape } from '@agoric/time';
 import { M } from '@agoric/store';
 
+/**
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery, PriceQuoteCreate, PriceAuthorityKit, PriceQuoteTrigger, MutableQuote,} from '@agoric/zoe/tools/types.js';
+ */
+
 const { quote: q, Fail } = assert;
 
 const trace = makeTracer('PA', false);

packages/zoe/src/contractSupport/priceAuthorityInitial.js

@@ -11,6 +11,10 @@ import { AmountMath } from '@agoric/ertp';
 import { multiplyBy } from './ratio.js';
 import { mintQuote } from './priceAuthorityTransform.js';
 
+/**
+ * @import {PriceAuthority, PriceDescription, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
+
 /**
  * Override `makeQuoteNotifier`, `quoteGiven` to provide an initial price
  * in case one is not yet available from the source.

packages/zoe/src/contractSupport/priceAuthorityTransform.js

@@ -4,7 +4,10 @@ import { Fail, assert } from '@agoric/assert';
 import { AmountMath } from '@agoric/ertp';
 import { makeNotifier } from '@agoric/notifier';
 
-/** @import {EOnly} from '@endo/eventual-send' */
+/**
+ * @import {EOnly} from '@endo/eventual-send';
+ * @import {MutableQuote, PriceAuthority, PriceQuote, PriceQuoteValue, PriceQuery,} from '@agoric/zoe/tools/types.js';
+ */
 
 /**
  * @param {Brand<'set'>} quoteBrand