Merge pull request #8705 from Agoric/gibson-2024-01-package-links

docs: Hyperlink package references

packages/ERTP/docs/INPUT_VALIDATION.md

@@ -2,7 +2,7 @@
 
 ## Requirements
 
-We want ERTP to be robust against malicious code in the same vat, so the ERTP must be robust without the kind of checks that we get for free in intervat communication going through `@endo/marshal` and `@agoric/swingset-vat`. In other words, the only tools at our disposal are being in a Hardened JS environment, and helpers that we import and call directly, such as `passStyleOf` from `@endo/marshal`.
+We want ERTP to be robust against malicious code in the same vat, so the ERTP must be robust without the kind of checks that we get for free in intervat communication going through [@endo/marshal](https://www.npmjs.com/package/@endo/marshal) and [@agoric/swingset-vat](../../SwingSet). In other words, the only tools at our disposal are being in a Hardened JS environment, and helpers that we import and call directly, such as `passStyleOf` from `@endo/marshal`.
 
 ## Malicious Behavior
 

packages/ERTP/docs/user-safety.md

@@ -4,14 +4,14 @@
 
 ERTP can be thought of as a protocol and an implementation. There
 could be multiple different implementations of the protocol, but for
-now, we just have one (@agoric/ertp) whose types specify the protocol.
+now, we just have one ([@agoric/ertp](..)) whose types specify the protocol.
 The distinction between protocol and implementation becomes important
 because when Zoe escrows assets for use in contracts, it does not
-verify that the assets were made using the latest @agoric/ertp
+verify that the assets were made using the latest `@agoric/ertp`
 implementation. This means that the issuers and brands of assets that
 users escrow may misbehave.
 
-Zoe specifically uses the @agoric/ertp implementation for contract invitations. 
+Zoe specifically uses the `@agoric/ertp` implementation for contract invitations. 
 
 For every new brand of token, there is:
 * A mint - this is the only object with the ability to mint tokens. To mint, call `mint.mintPayment`. 
@@ -64,4 +64,4 @@ Examples of receiving purported issuers that could be trusted:
 
 If the issuer was made in a Zoe contract (currently, the only way for users to create issuers on-chain), then asserting that the issuer was produced in a contract by inspecting the contract code itself and the mechanisms by which the issuer is exposed, is the best way to be assured that an issuer is well-behaving.
 
-Note that Zoe assumes that issuers may misbehave. Users of Zoe are required to rely on issuers at their own risk. A misbehaving issuer will not hurt Zoe or other users, but it will potentially hurt a user who makes an offer that `wants` or `gives` assets of the same `brand` as the issuer.
+Note that Zoe assumes that issuers may misbehave. Users of Zoe are required to rely on issuers at their own risk. A misbehaving issuer will not hurt Zoe or other users, but it will potentially hurt a user who makes an offer that `wants` or `gives` assets of the same `brand` as the issuer.

packages/SwingSet/docs/dynamic-vats.md

@@ -16,7 +16,7 @@ The ability to create new vats is not ambient: it requires access to the Vat Adm
 
 Vats are created from "bundlecaps", which are objects that represent installed source code bundles. See [bundles.md](./bundles.md) for details.
 
-The first step is to create a source bundle. To do this, you'll want to point the `bundleSource` function (from the `@endo/bundle-source` package) at a local source file. This file should export a function named `buildRootObject` (it can export other things too, perhaps for unit tests, but only `buildRootObject` will be used by the dynamic vat loader). Suppose your vat code is stored in `vat-counter.js`:
+The first step is to create a source bundle. To do this, you'll want to point the `bundleSource` function (from the [@endo/bundle-source](https://www.npmjs.com/package/@endo/bundle-source) package) at a local source file. This file should export a function named `buildRootObject` (it can export other things too, perhaps for unit tests, but only `buildRootObject` will be used by the dynamic vat loader). Suppose your vat code is stored in `vat-counter.js`:
 
 ```js
 export function buildRootObject() {

packages/SwingSet/docs/metering.md

@@ -71,7 +71,7 @@ await E(meter).get(); // -> { remaining: 100_000_999n, threshold: 50n }
 
 ## Notification
 
-The meter's `remaining` value will be deducted over time. When it crosses below `threshold`, the Notifier is updated. This is an instance of `@agoric/notifier`:
+The meter's `remaining` value will be deducted over time. When it crosses below `threshold`, the [@agoric/notifier](../../notifier) Notifier is updated:
 
 ```js
 const notifier = await E(meter).getNotifier();

packages/SwingSet/docs/virtual-objects.md

@@ -7,7 +7,7 @@ The kernel currently provides two secondary storage mechanisms for the use of (a
 - Virtual and durable objects
 - Persistent stores
 
-These are accessed via properties of the `VatData` global made available to vat code, or more stylishly by importing from `@agoric/vat-data` (that's a working placeholder module which we will be replacing it with a more ergonomic package name once we figure out what that should be).
+These are accessed via properties of the `VatData` global made available to vat code, or more stylishly by importing from [@agoric/vat-data](../../vat-data) (that's a working placeholder module which we will be replacing it with a more ergonomic package name once we figure out what that should be).
 
 The APIs described here all have to do with storing data on disk.  However, you should understand an important distinction made in these APIs between the labels "virtual" and "durable".  In our usage here, things that are "virtual" will automatically swap their state to disk storage and thus don't eat up RAM space in the running vat process even if they grow large in number.  In contrast, things that are "durable" are not only stored on disk but survive the lifetime of the vat process holding them and may be retrieved later in a future version of the vat.
 

packages/base-zone/README.md

@@ -6,4 +6,4 @@ allows library code to be agnostic to whether its objects are backed purely by
 the JS heap (ephemeral), pageable out to disk (virtual) or can be revived after
 a vat upgrade (durable).
 
-This library is used internally by [`@agoric/zone`](../zone/README.md); refer to it for more details.  Unless you are an author of a new Zone backing store type, or want to use `makeHeapZone` without introducing build dependencies on `@agoric/vat-data`, you should instead use `@agoric/zone`.
+This library is used internally by [@agoric/zone](../zone/README.md); refer to it for more details.  Unless you are an author of a new Zone backing store type, or want to use `makeHeapZone` without introducing build dependencies on [@agoric/vat-data](../vat-data/README.md), you should instead use [@agoric/zone](../zone/README.md).

packages/casting/README.md

@@ -42,7 +42,7 @@ The `followerOpts` argument in `makeFollower(leader, key, followerOpts)` provide
 - the `decode` option is a function to translate `buf: Uint8Array` into `data: string`
   - (default) - interpret buf as a utf-8 string, then `JSON.parse` it
 - the `unserializer` option can be
-  - (default) - release unserialized objects using `@agoric/marshal`'s `makeMarshal()`
+  - (default) - release unserialized objects using [@endo/marshal](https://www.npmjs.com/package/@endo/marshal)'s `makeMarshal()`
   - `null` - don't additionally unserialize data before releasing it
   - any unserializer object supporting `E(unserializer).fromCapData(data)`
 - the `crasher` option can be
@@ -65,8 +65,8 @@ The `followerOpts` argument in `makeFollower(leader, key, followerOpts)` provide
 
 This package currently depends on:
 - Hardened Javascript
-- `@agoric/notify` async iterable adapters to implement `iterateLatest`
-- `@endo/marshal` for default object unserialization
+- [@agoric/notifier](../notifier) async iterable adapters to implement `iterateLatest`
+- [@endo/marshal](https://www.npmjs.com/package/@endo/marshal) for default object unserialization
 - [CosmJS](https://github.com/cosmos/cosmjs) for proof verification, although [it does not yet support light client tracking of the validator set](https://github.com/cosmos/cosmjs/issues/492)
 - a bespoke follower of [WebSocket Tendermint events](https://docs.tendermint.com/master/tendermint-core/subscription.html#legacy-streaming-api)
 

packages/inter-protocol/docs/governance.md

@@ -2,7 +2,7 @@
 
 Inter Protocol is subject to two forms of governance. Like the entire chain, it's subject to BLDer DAO governance. This is sometimes called the "big hammer" because the DAO can approve running any code in the core ("core eval").
 
-There is also governance by an configurable electorate using a contract governor (see `@agoric/governance`). The _governor_ contract allows the electorate to execute governed API methods or set governed parameters of the _governed_ contract. In the conventional configuration of the Inter Protocol contracts there is electorate, which is called the "Economic Committee".
+There is also governance by an configurable electorate using a contract governor (see [@agoric/governance](../../governance)). The _governor_ contract allows the electorate to execute governed API methods or set governed parameters of the _governed_ contract. In the conventional configuration of the Inter Protocol contracts there is electorate, which is called the "Economic Committee".
 
 The *Economic Committee* (EC) can enact proposals through contracts governed by their charter. A contract is put under EC governance by adding its governance facet to the EC charter creatorFacet. At the time of writing, governed contracts include:
 

packages/store/docs/store-taxonomy.md

@@ -2,7 +2,7 @@
 
 Some dimensions on which our Stores differ. For each of these dimensions, in the headings below we indicate the dominant default choice with a plus (+). A given Store maker should document which non-default points in this design space it supports. For example, the `makeScalarMapStore` function makes stores that are Strong and Ephemeral and have Scalar keys and Passable values.  The name is explicit only about the dimensions in which it differs from the defaults.
 
-This package establishes the naming scheme, but only populates some of the choices below. It is left to higher layer packages, such as `@agoric/vat-data`, to provide some of the other choices explained below.
+This package establishes the naming scheme, but only populates some of the choices below. It is left to higher layer packages, such as [@agoric/vat-data](../../vat-data), to provide some of the other choices explained below.
 
 All stores are Far objects (a kind of remotable) that may be snapshotted to (or restored from) a corresponding pass-by-copy objects. MapStores snapshot into CopyMaps. SetStores snapshot into CopySets.
 
@@ -57,7 +57,7 @@ If we expect a weak store to outlive most of its keys, we consider it long lived
 
 ## Small+ vs Big
 
-There is no qualifier for small. Non-big stores are always small. The `@agoric/store` package implements only small stores. Big stores are provided by the `@agoric/vat-data` package.
+There is no qualifier for small. Non-big stores are always small. The [@agoric/store](../../store) package implements only small stores. Big stores are provided by the [@agoric/vat-data](../../vat-data) package.
 
 * ***`make*Store`*** <br>
 A small store is one that is expected to fit into a normal JavaScript object using JavaScript's normal heap memory and occupying room in vat snapshots.

packages/swing-store/docs/data-export.md

@@ -229,7 +229,7 @@ SwingStore contains components to accommodate all the various kinds of state tha
 * `kvStore`, a general-purpose string/string key-value table
 * `transcriptStore`: append-only vat deliveries, broken into "spans", delimited by heap snapshot events
 * `snapshotStore`: binary blobs containing JS engine heap state, to limit transcript replay depth
-* `bundleStore`: code bundles that can be imported with `@endo/import-bundle`
+* `bundleStore`: code bundles that can be imported with [@endo/import-bundle](https://www.npmjs.com/package/@endo/import-bundle)
 
 Currently, the SwingStore treats transcript spans, heap snapshots, and bundles as export artifacts, with hashes recorded in the export data for validation (and to remember exactly which artifacts are necessary). The `kvStore` is copied one-to-one into the export data (i.e. we keep a full shadow copy in IAVL), because that is the fastest way to ensure the `kvStore` data is fully available and validated.
 

packages/swingset-xsnap-supervisor/README.md

@@ -2,7 +2,7 @@
 
 This package provides the bundle necessary to convert an `xsnap` SES environment into a SwingSet vat worker.
 
-The basic xsnap package (@agoric/xsnap) provides two components. The first is the `xsnap` executable, which embeds the XS JavaScript engine inside a driver program that listens for commands on a socket. The second is a library which can launch that program as a child process, and sends/receives messages over the socket. The `@agoric/xsnap` API lets you perform three basic operations on the worker: evaluate a string of code, deliver a string to a globally-registered handler function, and instruct the XS engine to write out a heap snapshot.
+The basic xsnap package ([@agoric/xsnap](../xsnap)) provides two components. The first is the `xsnap` executable, which embeds the XS JavaScript engine inside a driver program that listens for commands on a socket. The second is a library which can launch that program as a child process, and sends/receives messages over the socket. The `@agoric/xsnap` API lets you perform three basic operations on the worker: evaluate a string of code, deliver a string to a globally-registered handler function, and instruct the XS engine to write out a heap snapshot.
 
 However this is not quite sufficient for use as a vat host, which needs a SES environment which can accept vat deliveries and issue syscalls. To build something more suitable, we need additional layers:
 

packages/vm-config/README.md

@@ -1,6 +1,6 @@
 # VM Config
 
-Factored out of @agoric/vats, by way of @agoric/boot.
+Factored out of [@agoric/vats](../vats), by way of [@agoric/boot](../boot).
 
 This is similar to `@agoric/boot` but because that has the integration testing of bootstrap, it depends on almost everything.
 

packages/wallet/README.md

@@ -2,8 +2,8 @@
 
 This directory contains two Agoric Wallet pieces:
 
-- `api` - the legacy "off-chain" wallet used by `@agoric/solo`
-- `ui` - the `@agoric/smart-wallet` user interface
+- `api` - the legacy "off-chain" wallet used by [@agoric/solo](../solo)
+- `ui` - the [@agoric/smart-wallet](../smart-wallet) user interface
 
 The smart wallet has not yet subsumed all the features of the off-chain wallet.  Until it does, we require the `api` directory.
 

packages/xsnap-lockdown/README.md

@@ -2,7 +2,7 @@
 
 This package provides the bundles necessary to prepare an Endo (aka SES: Secure ECMAScript) environment within an `xsnap` worker process.
 
-The basic xsnap package (@agoric/xsnap) provides two components. The first is the `xsnap-worker` executable, which embeds the XS JavaScript engine inside a driver program that listens for commands on a socket. The second is a library which can launch that program as a child process, and sends/receives messages over the socket. The `@agoric/xsnap` API lets you perform three basic operations on the worker: evaluate a string of code, deliver a string to a globally-registered handler function, and instruct the XS engine to write out a heap snapshot.
+The basic xsnap package ([@agoric/xsnap](../xsnap)) provides two components. The first is the `xsnap-worker` executable, which embeds the XS JavaScript engine inside a driver program that listens for commands on a socket. The second is a library which can launch that program as a child process, and sends/receives messages over the socket. The `@agoric/xsnap` API lets you perform three basic operations on the worker: evaluate a string of code, deliver a string to a globally-registered handler function, and instruct the XS engine to write out a heap snapshot.
 
 However this is not quite sufficient for use as a vat host, which needs a SES environment which can accept vat deliveries and issue syscalls. To build something more suitable, we need additional layers:
 

packages/zoe/docs/zoe-catalog-of-storage.md

@@ -1,5 +1,7 @@
 # Catalog of Zoe Maps/WeakMaps/Stores
 
+Stores are provided by [@agoric/store](../../store) and [@agoric/vat-data](../../vat-data).
+
 ## Zoe Service (one per chain)
 
 ### installations - native WeakSet

packages/zoe/docs/zoe-zcf.md

@@ -121,8 +121,8 @@ Eventually, the Zoe Service may be split into multiple vats, but for now, all of
 
 Contracts by default are private: unless the contract gives you an object by which you can get access, you do not have *any* access to the contract.
 
-Zoe specifically uses the @agoric/ertp implementation for contract
-invitations, but when Zoe escrows assets for use in contracts, Zoe does not verify that the assets were made using the latest @agoric/ertp implementation. 
+Zoe specifically uses the [@agoric/ertp](../../ERTP) implementation for contract
+invitations, but when Zoe escrows assets for use in contracts, Zoe does not verify that the assets were made using the latest [@agoric/ertp](../../ERTP) implementation. 
 
 A user can only receive an invitation to a contract instance if the contract code calls `zcf.makeInvitation(...`, which goes through the proper channels and asks Zoe to mint the invitation. No other contract code or other channel can create an invitation for a contract instance.