explicit type exports for agoric/notifier

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 */