explicit type exports for agoric/notifier (#9305)

refs: #6512

## Description

Progress on #6512, spawned from #9300.

This gives the @agoric/notifier package explicit exports.

Many downstream packages were relying on @agoric/notifier ambients for
types from @agoric/internal or Endo, so this also adds an `exported.js`
to @agoric/internal to provide those. (E.g. `ERef`).

### Security Considerations
none, types
<!-- 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
none, types
<!-- 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

might improve API docs of Notifier package
<!-- 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
CI
<!-- 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
none, types
<!-- What aspects of this PR are relevant to upgrading live production
systems, and how should they be addressed? -->

docs/typescript.md

@@ -6,7 +6,44 @@ Our use of TypeScript has to accomodate both .js development in agoric-sdk (whic
 
 - package entrypoint(s) exports explicit types
 - for packages upon which other packages expect ambient types:
-  - `exported.d.ts` exports the explicit types and ambient re-exports
+  - `exported.js` exports the explicit types and ambient re-exports
+
+## exported.js
+
+The `exported.js` re-exports types into global namespace, for consumers that expect these to
+be ambient. This could be called "ambient.js" but we retain the filename for backwards compatibility.
+
+The pattern is to make these two files like this at package root:
+
+
+`exported.js`
+
+```ts
+// Dummy file for .d.ts twin to declare ambients
+export {};
+```
+
+`exported.d.ts`
+
+```ts
+/** @file Ambient exports until https://github.com/Agoric/agoric-sdk/issues/6512 */
+/** @see {@link /docs/typescript.md} */
+/* eslint-disable -- doesn't understand .d.ts */
+import {
+  SomeType as _SomeType,
+} from './src/types.js';
+
+declare global {
+  export {
+    _SomeType as SomeType,
+  };
+}
+```
+
+Why the _ prefix? Because without it TS gets confused between the
+import and export symbols. ([h/t](https://stackoverflow.com/a/66588974))
+Note one downside vs ambients is that these types will appear to be on `globalThis`.
+
 
 ## Generating API docs
 

packages/ERTP/exported.d.ts

@@ -1,12 +1,10 @@
+/** @file Ambient exports until https://github.com/Agoric/agoric-sdk/issues/6512 */
+/** @see {@link /docs/typescript.md} */
 /* eslint-disable -- doesn't understand .d.ts */
 
+// XXX also explicit exports because `@agoric/ertp` top level confuses the type and value of `AssetKind`
 export * from './src/types.js';
 
-// XXX re-export types into global namespace, for consumers that expect these to
-//  be ambient. Why the _ prefix? Because without it TS gets confused between the
-//  import and export symbols. h/t https://stackoverflow.com/a/66588974
-//  Note one big downside vs ambients is that these types will appear to be on `globalThis`.
-// UNTIL https://github.com/Agoric/agoric-sdk/issues/6512
 import {
   Amount as _Amount,
   Brand as _Brand,

packages/ERTP/exported.js

@@ -1 +1,2 @@
 // Dummy file for .d.ts twin to declare ambients
+export {};

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

@@ -4,7 +4,10 @@ import { mustMatch } from '@agoric/store';
 import { E } from '@endo/far';
 import { AmountMath } from './amountMath.js';
 
-/** @import {Amount, AssetKind, AmountValue, AssetKindForValue, Payment, Brand, Purse} from './types.js' */
+/**
+ * @import {ERef} from '@endo/far');
+ * @import {Amount, AssetKind, AmountValue, AssetKindForValue, Payment, Brand, Purse} from './types.js'
+ */
 
 const { Fail } = assert;
 

packages/ERTP/src/paymentLedger.js

@@ -7,7 +7,9 @@ import { AmountMath } from './amountMath.js';
 import { preparePaymentKind } from './payment.js';
 import { preparePurseKind } from './purse.js';
 
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
 import '@agoric/store/exported.js';
+
 import { BrandI, makeIssuerInterfaces } from './typeGuards.js';
 
 /**

packages/ERTP/src/transientNotifier.js

@@ -4,7 +4,10 @@ import { makeScalarBigWeakMapStore } from '@agoric/vat-data';
 import { provideLazy } from '@agoric/store';
 import { makeNotifierKit } from '@agoric/notifier';
 
-/** @import {Purse} from './types.js' */
+/**
+ * @import {Purse} from './types.js';
+ * @import {LatestTopic, NotifierRecord} from '@agoric/notifier');
+ */
 
 // Note: Virtual for high cardinality, but *not* durable, and so
 // broken across an upgrade.

packages/ERTP/src/types.js

@@ -5,8 +5,9 @@ export {};
 
 /// <reference types="ses"/>
 /**
- * @import {Passable} from '@endo/pass-style')
- * @import {CopySet, Key} from '@endo/patterns')
+ * @import {ERef} from '@endo/far');
+ * @import {CopySet, Key} from '@endo/patterns');
+ * @import {LatestTopic, NotifierRecord} from '@agoric/notifier');
  */
 
 /**

packages/base-zone/src/index.js

@@ -1,5 +1,8 @@
 // @jessie-check
 
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
+import '@agoric/store/exported.js';
+
 // eslint-disable-next-line import/export
 export * from './exports.js';
 

packages/benchmark/src/benchmarkerator.js

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import '@endo/init/pre-bundle-source.js';
 import '@endo/init';
 
-// XXX The following four imports are present only to make `tsc` shut up.  They do no actual work.
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
 import '@agoric/vats/exported.js';
 import '@agoric/inter-protocol/exported.js';
 import '@agoric/zoe/exported.js';

packages/boot/test/bootstrapTests/ibcClientMock.js

@@ -3,6 +3,10 @@
 import { Far } from '@endo/far';
 import { V as E } from '@agoric/vat-data/vow.js';
 
+/**
+ * @import {ListenHandler, PortAllocator} from '@agoric/network';
+ */
+
 /**
  * @param {ZCF} zcf
  * @param {{

packages/boot/test/bootstrapTests/ibcServerMock.js

@@ -7,6 +7,10 @@ import { V as E } from '@agoric/vat-data/vow.js';
 const { quote: q, Fail } = assert;
 const { log } = console;
 
+/**
+ * @import {ListenHandler, PortAllocator} from '@agoric/network';
+ */
+
 /**
  *
  * @param {ZCF} zcf

packages/boot/test/bootstrapTests/zcfProbe.js

@@ -1,3 +1,4 @@
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
 import '@agoric/zoe/exported.js';
 
 import { makeTracer } from '@agoric/internal';

packages/boot/tools/supports.ts

@@ -17,7 +17,10 @@ import { initSwingStore } from '@agoric/swing-store';
 import { loadSwingsetConfigFile } from '@agoric/swingset-vat';
 import { makeSlogSender } from '@agoric/telemetry';
 import { TimeMath, Timestamp } from '@agoric/time';
+
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
 import '@agoric/vats/exported.js';
+
 import {
   boardSlottingMarshaller,
   slotToBoardRemote,

packages/cache/src/main.js

@@ -1,5 +1,8 @@
 // @jessie-check
 
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
+import '@agoric/internal/exported.js';
+
 // eslint-disable-next-line import/export
 export * from './types.js';
 export * from './store.js';

packages/casting/src/main.js

@@ -1,5 +1,7 @@
 // @jessie-check
 
+import '@agoric/internal/exported.js';
+
 // eslint-disable-next-line import/export
 export * from './types.js'; // no named exports
 export * from './defaults.js';

packages/casting/src/types.js

@@ -1,11 +1,11 @@
 // @jessie-check
 
-// Make this a module.
-import '@agoric/notifier';
-
+// Ensure this is a module.
 export {};
 
-/** @import { ERef } from '@endo/far' */
+/**
+ * @import {Notifier, Subscription} from '@agoric/notifier';
+ */
 
 /**
  * @typedef {object} LeaderOptions

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

@@ -1,6 +1,10 @@
 // @ts-check
 const t = 'makeCoreProposalBehavior';
 
+/**
+ * @import {Installation} from '@agoric/zoe/src/zoeService/utils.js';
+ */
+
 /**
  * TODO import these from @agoric/vats when the types are better managed
  *

packages/governance/exported.d.ts

@@ -1,12 +1,7 @@
+/** @file Ambient exports until https://github.com/Agoric/agoric-sdk/issues/6512 */
+/** @see {@link /docs/typescript.md} */
 /* eslint-disable -- doesn't understand .d.ts */
 
-export * from './src/types.js';
-
-// XXX re-export types into global namespace, for consumers that expect these to
-//  be ambient. Why the _ prefix? Because without it TS gets confused between the
-//  import and export symbols. h/t https://stackoverflow.com/a/66588974
-//  Note one big downside vs ambients is that these types will appear to be on `globalThis`.
-// UNTIL https://github.com/Agoric/agoric-sdk/issues/6512
 import {
   GovernanceFacetKit as _GovernanceFacetKit,
   GovernanceTerms as _GovernanceTerms,

packages/governance/src/contractGovernance/governParam.js

@@ -9,6 +9,7 @@ import {
   QuorumRule,
 } from '../question.js';
 import { ParamChangesQuestionDetailsShape } from '../typeGuards.js';
+
 /**
  * @import {ParamValue, ParamChangePositions, QuestionSpec, ChangeParamsPosition, ParamChangeIssue, ParamGovernor, ParamManagerRetriever, PoserFacet, VoteOnParamChanges} from '../types.js';
  */

packages/governance/src/index.js

@@ -1,8 +1,7 @@
 // XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
+import '@agoric/internal/exported.js';
 import '@agoric/ertp/exported.js';
-import '@agoric/zoe/src/contractFacet/types-ambient.js';
-import '@agoric/zoe/tools/types-ambient.js';
-import '@agoric/zoe/src/types.js';
+import '@agoric/zoe/exported.js';
 
 /// <reference path="./types-ambient.js" />
 

packages/governance/src/types.js

@@ -1,3 +1,5 @@
+import '@agoric/zoe/src/zoeService/types-ambient.js';
+
 export {};
 
 /** @import {ContractStartFunction} from '@agoric/zoe/src/zoeService/utils.js' */

packages/governance/test/unitTests/test-binaryballotCount.js

@@ -1,6 +1,9 @@
 /* eslint @typescript-eslint/no-floating-promises: "warn" */
 import { test } from '@agoric/zoe/tools/prepare-test-env-ava.js';
+
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
 import '@agoric/zoe/exported.js';
+
 import { E } from '@endo/eventual-send';
 import buildManualTimer from '@agoric/zoe/tools/manualTimer.js';
 import { makeHandle } from '@agoric/zoe/src/makeHandle.js';

packages/governance/test/unitTests/test-committee.js

@@ -1,5 +1,6 @@
 import { test } from '@agoric/zoe/tools/prepare-test-env-ava.js';
 
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
 import '@agoric/zoe/exported.js';
 
 import { makeMockChainStorageRoot } from '@agoric/internal/src/storage-test-utils.js';

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

@@ -1,3 +1,5 @@
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
+import '@agoric/internal/exported.js';
 import '@agoric/governance/exported.js';
 import '@agoric/zoe/exported.js';
 import '@agoric/zoe/src/contracts/exported.js';

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

@@ -1,9 +1,11 @@
 // @jessie-check
 
+// XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512
 import '../../exported.js';
+import '@agoric/governance/exported.js';
+import '@agoric/vats/src/core/types-ambient.js';
 
 import { AmountMath } from '@agoric/ertp';
-import '@agoric/governance/exported.js';
 import { deeplyFulfilledObject, makeTracer } from '@agoric/internal';
 import { makeStorageNodeChild } from '@agoric/internal/src/lib-chainStorage.js';
 import { E } from '@endo/far';

packages/inter-protocol/src/provisionPoolKit.js

@@ -26,6 +26,7 @@ const { details: X, quote: q, Fail } = assert;
 /**
  * @import {ERef} from '@endo/far'
  * @import {Amount} from '@agoric/ertp/src/types.js'
+ * @import {Bank, BankManager} from '@agoric/vats/src/vat-bank.js'
  */
 
 /**
@@ -59,7 +60,6 @@ const { details: X, quote: q, Fail } = assert;
  *
  * @param {(depositBank: ERef<Bank>) => Promise<void>} sendInitialPayment
  * @param {() => void} onProvisioned
- * @import {Bank} from '@agoric/vats/src/vat-bank.js'
  */
 export const makeBridgeProvisionTool = (sendInitialPayment, onProvisioned) => {
   /** @param {ProvisionPoolKitReferences} refs */