explicit exports of Zoe service and contract facet types (#11075)

refs: #6343
refs: #10811

## Description
While working to move Fast USDC (#10811) I kept running into problems with types resolving. I started working on the tech debt of  #6343 and slipped down that rabbit hole.

This makes the ambient type declarations of ZoeService and ZCF modules into explicit exports and updates a ton of code to cope. Review by commit!

Some collateral improvements along the way:
- governance type improvements
- return types of Zoe helpers
- Typesscript 5.8 release
- cosmic-swingset conflicting dependencies

### Security Considerations
none

### Scaling Considerations
none

### Documentation Considerations
I don't think we have docs on type imports

### Testing Considerations
CI

### Upgrade Considerations
This will break modules importing the `types-ambient.js` files that are gone. Those were deep imports so not part of the package semver.

multichain-testing/package.json

@@ -39,7 +39,7 @@
     "patch-package": "^8.0.0",
     "starshipjs": "2.4.1",
     "ts-blank-space": "^0.4.4",
-    "typescript": "~5.8.1-rc"
+    "typescript": "~5.8.2"
   },
   "resolutions": {
     "axios": "1.6.7",

multichain-testing/test/fast-usdc/fu-actors.ts

@@ -12,6 +12,7 @@ import type { ExecutionContext } from 'ava';
 import { makeDoOffer, type WalletDriver } from '../../tools/e2e-tools.js';
 import type { createWallet } from '../../tools/wallet.js';
 import type { commonSetup, SetupContextWithWallets } from '../support.js';
+import type { InvitationDetails } from '@agoric/zoe';
 
 const { fromEntries } = Object;
 

multichain-testing/yarn.lock

@@ -4925,7 +4925,7 @@ __metadata:
     patch-package: "npm:^8.0.0"
     starshipjs: "npm:2.4.1"
     ts-blank-space: "npm:^0.4.4"
-    typescript: "npm:~5.8.1-rc"
+    typescript: "npm:~5.8.2"
   languageName: unknown
   linkType: soft
 
@@ -5468,13 +5468,13 @@ __metadata:
   languageName: node
   linkType: hard
 
-"typescript@npm:~5.8.1-rc":
-  version: 5.8.1-rc
-  resolution: "typescript@npm:5.8.1-rc"
+"typescript@npm:~5.8.2":
+  version: 5.8.2
+  resolution: "typescript@npm:5.8.2"
   bin:
     tsc: bin/tsc
     tsserver: bin/tsserver
-  checksum: 10c0/7692b2584d0bddbab2b9a76457908276cb968935b9e1a89b7429939b1c02c7c47b5b23f1e989e18bf441fc545a311f02e143e7594a3914e240554637011a7d70
+  checksum: 10c0/5c4f6fbf1c6389b6928fe7b8fcd5dc73bb2d58cd4e3883f1d774ed5bd83b151cbac6b7ecf11723de56d4676daeba8713894b1e9af56174f2f9780ae7848ec3c6
   languageName: node
   linkType: hard
 
@@ -5488,13 +5488,13 @@ __metadata:
   languageName: node
   linkType: hard
 
-"typescript@patch:typescript@npm%3A~5.8.1-rc#optional!builtin<compat/typescript>":
-  version: 5.8.1-rc
-  resolution: "typescript@patch:typescript@npm%3A5.8.1-rc#optional!builtin<compat/typescript>::version=5.8.1-rc&hash=5786d5"
+"typescript@patch:typescript@npm%3A~5.8.2#optional!builtin<compat/typescript>":
+  version: 5.8.2
+  resolution: "typescript@patch:typescript@npm%3A5.8.2#optional!builtin<compat/typescript>::version=5.8.2&hash=5786d5"
   bin:
     tsc: bin/tsc
     tsserver: bin/tsserver
-  checksum: 10c0/45267f3c53240100da1d53ec8ebaa008f019055fe339c79baf596bab180aab2821751781bfc3202d5f6180fe01200aed9ebf45dec84490ef3a9d90359326c075
+  checksum: 10c0/5448a08e595cc558ab321e49d4cac64fb43d1fa106584f6ff9a8d8e592111b373a995a1d5c7f3046211c8a37201eb6d0f1566f15cdb7a62a5e3be01d087848e2
   languageName: node
   linkType: hard
 

package.json

@@ -36,13 +36,13 @@
     "type-coverage": "^2.27.1",
     "typedoc": "^0.26.7",
     "typedoc-plugin-markdown": "^4.2.1",
-    "typescript": "~5.8.1-rc",
-    "typescript-eslint": "^8.22.0"
+    "typescript": "~5.8.2",
+    "typescript-eslint": "^8.26.0"
   },
   "resolutions": {
     "**/protobufjs": "^7.2.6",
     "**/@types/estree": "^1.0.0",
-    "@endo/eslint-plugin/typescript-eslint": "^8.22.0"
+    "@endo/eslint-plugin/typescript-eslint": "^8.26.0"
   },
   "engines": {
     "node": "^18.12 || ^20.9"

packages/ERTP/package.json

@@ -77,6 +77,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 91.77
+    "atLeast": 91.88
   }
 }

packages/ERTP/src/amountMath.js

@@ -9,7 +9,7 @@ import { copyBagMathHelpers } from './mathHelpers/copyBagMathHelpers.js';
 
 /**
  * @import {CopyBag, CopySet} from '@endo/patterns';
- * @import {Amount, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
+ * @import {Amount, AmountValue, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
  */
 
 // NB: AssetKind is both a constant for enumerated values and a type for those values.
@@ -105,15 +105,17 @@ const assertValueGetAssetKind = value => {
  *
  * Made available only for testing, but it is harmless for other uses.
  *
- * @template V
+ * @template {AmountValue} V
  * @param {V} value
  * @returns {MathHelpers<V>}
  */
 export const assertValueGetHelpers = value =>
   // @ts-expect-error cast
   helpers[assertValueGetAssetKind(value)];
 
-/** @type {(allegedBrand: Brand, brand?: Brand) => void} */
+/**
+ * @type {(allegedBrand: Brand<any>, brand?: Brand<any>) => void}
+ */
 const optionalBrandCheck = (allegedBrand, brand) => {
   if (brand !== undefined) {
     assertRemotable(brand, 'brand');

packages/ERTP/src/issuerKit.js

@@ -13,6 +13,8 @@ import { preparePaymentLedger } from './paymentLedger.js';
  * @import {AdditionalDisplayInfo, RecoverySetsOption, IssuerKit, PaymentLedger} from './types.js';
  * @import {ShutdownWithFailure} from '@agoric/swingset-vat';
  * @import {TypedPattern} from '@agoric/internal';
+ * @import {CopyTaggedInterface, Key, RemotableObject} from '@endo/patterns';
+ * @import {Pattern} from '@endo/patterns';
  */
 
 /**
@@ -252,7 +254,7 @@ harden(makeDurableIssuerKit);
  *   anything else is corrupted by that corrupted state. See
  *   https://github.com/Agoric/agoric-sdk/issues/3434
  * @param {O} [options]
- * @returns {O['elementShape'] extends TypedPattern<infer T>
+ * @returns {O['elementShape'] extends TypedPattern<infer T extends Key>
  *     ? IssuerKit<K, T>
  *     : IssuerKit<K>}
  */
@@ -328,7 +330,7 @@ harden(prepareIssuerKit);
  *   anything else is corrupted by that corrupted state. See
  *   https://github.com/Agoric/agoric-sdk/issues/3434
  * @param {O} [options]
- * @returns {O['elementShape'] extends TypedPattern<infer T>
+ * @returns {O['elementShape'] extends TypedPattern<infer T extends Key>
  *     ? IssuerKit<K, T>
  *     : IssuerKit<K>}
  */

packages/ERTP/src/legacy-payment-helpers.js

@@ -7,7 +7,7 @@ import { AmountMath } from './amountMath.js';
 
 /**
  * @import {ERef} from '@endo/far';
- * @import {Key} from '@endo/patterns';
+ * @import {Key, Pattern} from '@endo/patterns';
  * @import {Amount, AssetKind, Payment, Purse} from './types.js';
  */
 

packages/ERTP/src/paymentLedger.js

@@ -12,6 +12,7 @@ import { preparePurseKind } from './purse.js';
 import { BrandI, makeIssuerInterfaces } from './typeGuards.js';
 
 /**
+ * @import {Key, Pattern} from '@endo/patterns';
  * @import {Amount, AssetKind, DisplayInfo, PaymentLedger, Payment, Brand, RecoverySetsOption, Purse, Issuer, Mint} from './types.js'
  * @import {ShutdownWithFailure} from '@agoric/swingset-vat'
  * @import {TypedPattern} from '@agoric/internal';

packages/ERTP/src/typeGuards.js

@@ -4,6 +4,7 @@ import { M, matches, getInterfaceGuardPayload } from '@endo/patterns';
 /**
  * @import {AmountValue, Ratio} from './types.js'
  * @import {TypedPattern} from '@agoric/internal'
+ * @import {CopyBag, CopySet, Pattern} from '@endo/patterns';
  */
 
 export const BrandShape = M.remotable('Brand');

packages/SwingSet/package.json

@@ -100,6 +100,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 76.28
+    "atLeast": 76.25
   }
 }

packages/agoric-cli/package.json

@@ -100,6 +100,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 78.73
+    "atLeast": 78.96
   }
 }

packages/base-zone/src/is-passable.js

@@ -1,5 +1,9 @@
 import { isPassable as realIsPassable } from '@endo/pass-style';
 
+/**
+ * @import {Passable} from '@endo/pass-style';
+ */
+
 /**
  * @deprecated Import `isPassable` directly from `@endo/pass-style`
  * @param {any} specimen

packages/base-zone/src/types.js

@@ -7,6 +7,7 @@ import { watchPromise } from './watch-promise.js';
 export {};
 
 /**
+ * @import {MapStore, SetStore, StoreOptions, WeakMapStore, WeakSetStore} from '@agoric/store';
  * @import {Key} from '@endo/patterns';
  * @import {Passable} from '@endo/pass-style';
  */

packages/boot/package.json

@@ -95,6 +95,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 91.27
+    "atLeast": 91.39
   }
 }

packages/builders/package.json

@@ -81,6 +81,6 @@
     "workerThreads": false
   },
   "typeCoverage": {
-    "atLeast": 91.57
+    "atLeast": 91.55
   }
 }

packages/cache/src/cache.js

@@ -6,6 +6,7 @@ import { makeScalarStoreCoordinator } from './store.js';
 
 /**
  * @import {Passable, RemotableObject} from '@endo/pass-style';
+ * @import {Key, Pattern} from '@endo/patterns';
  */
 
 /**

packages/cache/src/store.js

@@ -4,7 +4,11 @@ import { matches, makeScalarMapStore } from '@agoric/store';
 import { makeScalarBigMapStore } from '@agoric/vat-data';
 import { untilTrue } from '@agoric/internal';
 import { withGroundState, makeState } from './state.js';
-/** @import {Passable} from '@endo/pass-style' */
+
+/**
+ * @import {Passable, RemotableObject} from '@endo/pass-style';
+ * @import {Key, Pattern} from '@endo/patterns';
+ */
 
 /**
  * @param {(obj: Passable) => Passable} [sanitize]

packages/cache/src/types.js

@@ -10,6 +10,7 @@ export {};
 /**
  * @import { ERef } from '@endo/far'
  * @import {Passable} from '@endo/pass-style'
+ * @import {Key, Pattern} from '@endo/patterns';
  */
 
 /**

packages/cosmic-proto/package.json

@@ -173,7 +173,7 @@
     "ava": "^5.3.1",
     "rimraf": "^5.0.0",
     "tsd": "^0.31.1",
-    "typescript": "~5.8.1-rc"
+    "typescript": "~5.8.2"
   },
   "dependencies": {
     "@endo/base64": "^1.0.9",

packages/cosmic-swingset/package.json

@@ -53,11 +53,9 @@
   },
   "devDependencies": {
     "@agoric/kmarshal": "^0.1.0",
-    "@endo/eventual-send": "^1.2.8",
     "ava": "^5.3.0",
     "better-sqlite3": "^9.1.1",
-    "c8": "^10.1.2",
-    "ses": "^1.10.0"
+    "c8": "^10.1.2"
   },
   "publishConfig": {
     "access": "public"
@@ -75,6 +73,6 @@
     "timeout": "20m"
   },
   "typeCoverage": {
-    "atLeast": 83.4
+    "atLeast": 84.13
   }
 }

packages/deploy-script-support/package.json

@@ -72,6 +72,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 83.71
+    "atLeast": 83.92
   }
 }

packages/deploy-script-support/src/depositInvitation.js

@@ -1,6 +1,10 @@
 // @ts-check
 import { E } from '@endo/far';
 
+/**
+ * @import {InvitationDetails} from '@agoric/zoe';
+ */
+
 /**
  * @param {ERef<Purse>} zoeInvitationPurse
  */

packages/deploy-script-support/src/offer.js

@@ -4,7 +4,10 @@ import { E } from '@endo/far';
 // Avoid pulling in too many dependencies like notifiers
 import { AmountMath } from '@agoric/ertp/src/amountMath.js';
 
-/** @import {Petname} from '@agoric/deploy-script-support/src/externalTypes.js' */
+/**
+ * @import {Petname} from '@agoric/deploy-script-support/src/externalTypes.js';
+ * @import {InvitationDetails, Proposal} from '@agoric/zoe';
+ */
 
 /**
  * @typedef {object} OfferHelperConfig

packages/fast-usdc/test/exos/settler.test.ts

@@ -11,6 +11,7 @@ import fetchedChainInfo from '@agoric/orchestration/src/fetched-chain-info.js';
 import { buildVTransferEvent } from '@agoric/orchestration/tools/ibc-mocks.js';
 import type { Zone } from '@agoric/zone';
 import type { EReturn } from '@endo/far';
+import type { ZcfSeatKit } from '@agoric/zoe';
 import { PendingTxStatus, TxStatus } from '../../src/constants.js';
 import {
   prepareSettler,

packages/governance/package.json

@@ -76,6 +76,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 89.48
+    "atLeast": 89.54
   }
 }

packages/governance/src/binaryVoteCounter.js

@@ -19,6 +19,7 @@ import { makeQuorumCounter } from './quorumCounter.js';
 
 /**
  * @import {MapStore} from '@agoric/swingset-liveslots';
+ * @import {ZCF} from '@agoric/zoe';
  * @import {BuildVoteCounter, OutcomeRecord, Position, QuestionSpec, VoteStatistics} from './types.js';
  */
 

packages/governance/src/committee.js

@@ -17,6 +17,7 @@ import { prepareVoterKit } from './voterKit.js';
 
 /**
  * @import {MapStore} from '@agoric/swingset-liveslots';
+ * @import {ContractMeta, Invitation, ZCF} from '@agoric/zoe';
  * @import {ElectorateCreatorFacet, CommitteeElectoratePublic, QuestionDetails, OutcomeRecord, AddQuestion} from './types.js';
  */
 

packages/governance/src/contractGovernance/governApi.js

@@ -11,6 +11,7 @@ import {
 } from '../question.js';
 
 /**
+ * @import {ContractMeta, Installation, Instance, Invitation, ZCF} from '@agoric/zoe';
  * @import {Passable, RemotableObject} from '@endo/pass-style';
  * @import {Position, ApiGovernor, ApiInvocationIssue, PoserFacet, VoteOnApiInvocation, GovernedApis} from '../types.js';
  */

packages/governance/src/contractGovernance/governFilter.js

@@ -11,6 +11,7 @@ import {
 } from '../question.js';
 
 /**
+ * @import {ContractMeta, Installation, Instance, Invitation, ZCF} from '@agoric/zoe';
  * @import {Position, ApiGovernor, ApiInvocationIssue, PoserFacet, VoteOnApiInvocation, FilterGovernor, GovernedCreatorFacet, OfferFilterIssue, VoteOnOfferFilter} from '../types.js';
  */
 

packages/governance/src/contractGovernance/governParam.js

@@ -12,6 +12,7 @@ import {
 import { ParamChangesQuestionDetailsShape } from '../typeGuards.js';
 
 /**
+ * @import {ContractMeta, Installation, Instance, Invitation, ZCF} from '@agoric/zoe';
  * @import {ParamValue, ParamChangePositions, QuestionSpec, ChangeParamsPosition, ParamChangeIssue, ParamGovernor, ParamManagerRetriever, PoserFacet, VoteOnParamChanges} from '../types.js';
  */
 

packages/governance/src/contractGovernance/paramManager.js

@@ -20,6 +20,7 @@ import { CONTRACT_ELECTORATE } from './governParam.js';
 
 /**
  * @import {MapStore} from '@agoric/swingset-liveslots';
+ * @import {ContractMeta, Installation, Instance, Invitation, ZCF} from '@agoric/zoe';
  * @import {AnyParamManager, GovernanceSubscriptionState, ParamManagerBase, ParamStateRecord, ParamValueTyped, UpdateParams} from '../types.js';
  */
 

packages/governance/src/contractGovernance/typedParamManager.js

@@ -5,6 +5,7 @@ import { CONTRACT_ELECTORATE } from './governParam.js';
 import { makeParamManagerBuilder } from './paramManager.js';
 
 /**
+ * @import {ContractMeta, Installation, Instance, Invitation, ZCF} from '@agoric/zoe';
  * @import {VoteCounterCreatorFacet, VoteCounterPublicFacet, QuestionSpec, OutcomeRecord, AddQuestion, AddQuestionReturn, GovernanceSubscriptionState, GovernanceTerms, ParamManagerBase, ParamStateRecord, ParamValueForType, UpdateParams} from '../types.js';
  * @import {ParamType} from '../constants.js';
  */

packages/governance/src/contractGovernor.js

@@ -9,6 +9,7 @@ import { prepareContractGovernorKit } from './contractGovernorKit.js';
 import { ParamChangesQuestionDetailsShape } from './typeGuards.js';
 
 /**
+ * @import {ContractMeta, Installation, Instance, Invitation, ZCF} from '@agoric/zoe';
  * @import {GovernableStartFn, GovernorCreatorFacet, GovernorPublic, ParamChangeIssueDetails} from './types.js';
  */
 
@@ -62,6 +63,7 @@ export const validateQuestionFromCounter = async (
   electorate,
   voteCounter,
 ) => {
+  /** @type {Promise<any>} */
   const counterPublicP = E(zoe).getPublicFacet(voteCounter);
   const questionDetails = await E(counterPublicP).getDetails();