Align Agoric docs integration with latest SDK and stabilize CI Node versioning

.github/workflows/test-build.yml

@@ -8,20 +8,33 @@ on:
     branches: [$default-branch]
   pull_request:
 
+env:
+  NODE_NEW_VERSION: 'lts/jod'
+
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [18.x]
+        # node-new keeps required job names stable; resolved to NODE_NEW_VERSION.
+        node-version: ['node-new']
     steps:
       - name: Checkout
         uses: actions/checkout@v3
 
-      - name: Use Node.js ${{ matrix.node-version }}
+      - name: Resolve Node.js version
+        id: resolve-node-version
+        run: |
+          if [ "${{ matrix.node-version }}" = "node-new" ]; then
+            echo "node-version=${{ env.NODE_NEW_VERSION }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "node-version=${{ matrix.node-version }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Use Node.js ${{ steps.resolve-node-version.outputs.node-version }}
         uses: actions/setup-node@v3
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: ${{ steps.resolve-node-version.outputs.node-version }}
 
       - name: Install, Build, Check Links
         run: |

.github/workflows/test-getting-started.yml

@@ -7,17 +7,37 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+
+env:
+  NODE_NEW_VERSION: 'lts/jod'
+
 jobs:
   getting_started:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # node-new keeps required job names stable; resolved to NODE_NEW_VERSION.
+        node-version: ['node-new']
     steps:
-      - name: Use Node.js
+      - name: Resolve Node.js version
+        id: resolve-node-version
+        run: |
+          if [ "${{ matrix.node-version }}" = "node-new" ]; then
+            echo "node-version=${{ env.NODE_NEW_VERSION }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "node-version=${{ matrix.node-version }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Use Node.js ${{ steps.resolve-node-version.outputs.node-version }}
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: ${{ steps.resolve-node-version.outputs.node-version }}
       - name: Creating Your Dapp From a Template
         run: yarn create @agoric/dapp offer-up
       - name: Install dependencies
+        env:
+          PUPPETEER_SKIP_DOWNLOAD: '1'
+          CYPRESS_INSTALL_BINARY: '0'
         run: |
           cd offer-up
           corepack enable

.github/workflows/test-markdown.yml

@@ -8,20 +8,33 @@ on:
     branches: [main]
   pull_request:
 
+env:
+  NODE_NEW_VERSION: 'lts/jod'
+
 jobs:
   lint-markdown:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [18.x]
+        # node-new keeps required job names stable; resolved to NODE_NEW_VERSION.
+        node-version: ['node-new']
     steps:
       - name: Checkout
         uses: actions/checkout@v3
 
-      - name: Use Node.js ${{ matrix.node-version }}
+      - name: Resolve Node.js version
+        id: resolve-node-version
+        run: |
+          if [ "${{ matrix.node-version }}" = "node-new" ]; then
+            echo "node-version=${{ env.NODE_NEW_VERSION }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "node-version=${{ matrix.node-version }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Use Node.js ${{ steps.resolve-node-version.outputs.node-version }}
         uses: actions/setup-node@v3
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: ${{ steps.resolve-node-version.outputs.node-version }}
       - name: Lint
         run: |
           corepack enable

.github/workflows/test-snippets.yml

@@ -8,12 +8,16 @@ on:
     branches: [$default-branch]
   pull_request:
 
+env:
+  NODE_NEW_VERSION: 'lts/jod'
+
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [18.x]
+        # node-new keeps required job names stable; resolved to NODE_NEW_VERSION.
+        node-version: ['node-new']
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -41,10 +45,19 @@ jobs:
           path: agoric-sdk
           ref: ${{steps.get-branch.outputs.result}}
 
-      - name: Use Node.js ${{ matrix.node-version }}
+      - name: Resolve Node.js version
+        id: resolve-node-version
+        run: |
+          if [ "${{ matrix.node-version }}" = "node-new" ]; then
+            echo "node-version=${{ env.NODE_NEW_VERSION }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "node-version=${{ matrix.node-version }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Use Node.js ${{ steps.resolve-node-version.outputs.node-version }}
         uses: actions/setup-node@v3
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: ${{ steps.resolve-node-version.outputs.node-version }}
 
       - name: Setup and link agoric-sdk packages
         run: |

.gitignore

@@ -13,3 +13,4 @@ main/.vitepress/cache/
 !.yarn/releases
 !.yarn/sdks
 !.yarn/versions
+offer-up/

.node-version

@@ -1 +1 @@
-v20.18.3
+lts/jod

main/guides/getting-started/explainer-how-to-make-an-offer.md

@@ -8,5 +8,3 @@ Take a look at our detailed [tutorial on how the UI for making offers](/guides/g
 
 Here is how the UI looks after completion:
 ![The UI look after completing the UI tutorial](./assets/dapp-offer-up-run.gif)
-
-

main/guides/js-programming/index.md

@@ -34,23 +34,20 @@ Vats may be on remote machines, including massively replicated machines such as
 The framework includes:
 
 - **[Hardened JavaScript](./hardened-js)**
-
   - Hardened JavaScript provides a platform for
     making objects that can interact with code you don't completely trust,
     without being vulnerable to bugs or bad intentions.
     We introduce [object capabilities](./hardened-js#object-capabilities-ocaps) and how to use them
     to apply the [principle of least authority](./hardened-js#the-principle-of-least-authority-pola).
 
 - **[`E()` for Eventual Send to Remote Presences](./eventual-send)**
-
   - The `E()` wrapper function lets
     you invoke methods within or between vats.
     Given a local representative (a _presence_) for a remote object,
     it sends messages to the origin of the presence.
     `E(obj).myMethod(...args)` is an asynchronous form of `obj.myMethod(...args)`.
 
 - **[`Far()`, Remoteable Objects, and Marshaling](./far)**
-
   - Objects used across vats are called _remotables_.
     To mark an object for exporting from a vat, use the `Far()` function.
 

main/reference/zoe-api/zoe.md

@@ -293,19 +293,16 @@ It returns a **Promise** for a **StartInstanceResult** object. The object consis
 The **adminFacet** has four methods:
 
 - **getVatShutdownPromise()**
-
   - Returns a promise that resolves to reason (the value passed to **fail(reason)**) or
     completion (the value passed to **exit(completion)**) when this newly started instance terminates.
 
 - **restartContract(newPrivateArgs?)**
-
   - **newPrivateArgs**: **any** - Optional
   - returns VatUpgradeResults (a record with one field: incarnationNumber)
 
   Restarts the contract without changing the contract bundle
 
 - **upgradeContract(contractBundleId, newPrivateArgs)**
-
   - **contractBundleId**: **string**
   - **newPrivateArgs**: **any** - Optional
 
@@ -317,7 +314,6 @@ The **adminFacet** has four methods:
   process of upgrading contracts.
 
 - **terminateContract(reason)**
-
   - **reason**: **Error**
 
   terminates the contract. `reason` will be provided as the failure reason.

package.json

@@ -35,9 +35,9 @@
   },
   "homepage": "https://github.com/Agoric/documentation#readme",
   "dependencies": {
-    "@agoric/ertp": "0.16.3-dev-25728ab.0",
-    "@agoric/zoe": "0.26.3-dev-25728ab.0",
-    "@agoric/zone": "0.2.3-dev-25728ab.0",
+    "@agoric/ertp": "0.16.3-dev-16059a9.0.16059a9",
+    "@agoric/zoe": "0.26.3-dev-16059a9.0.16059a9",
+    "@agoric/zone": "0.2.3-dev-16059a9.0.16059a9",
     "@endo/errors": "^1.2.13",
     "@endo/far": "^1.1.14",
     "@endo/marshal": "^1.8.0",
@@ -46,12 +46,12 @@
     "typescript": "^4.9.5"
   },
   "devDependencies": {
-    "@agoric/cosmic-swingset": "0.41.4-dev-25728ab.0",
-    "@agoric/ertp": "0.16.3-dev-25728ab.0",
-    "@agoric/notifier": "0.6.3-dev-25728ab.0",
-    "@agoric/solo": "0.10.4-dev-25728ab.0",
-    "@agoric/store": "0.9.3-dev-25728ab.0",
-    "@agoric/vats": "0.15.2-dev-25728ab.0",
+    "@agoric/cosmic-swingset": "0.41.4-dev-16059a9.0.16059a9",
+    "@agoric/ertp": "0.16.3-dev-16059a9.0.16059a9",
+    "@agoric/notifier": "0.6.3-dev-16059a9.0.16059a9",
+    "@agoric/solo": "0.10.4-dev-16059a9.0.16059a9",
+    "@agoric/store": "0.9.3-dev-16059a9.0.16059a9",
+    "@agoric/vats": "0.15.2-dev-16059a9.0.16059a9",
     "@endo/bundle-source": "^4.1.2",
     "@endo/eventual-send": "^1.3.4",
     "@endo/init": "^1.1.12",
@@ -64,11 +64,11 @@
     "eslint-config-jessie": "^0.0.6",
     "eslint-config-prettier": "^8.10.0",
     "eslint-plugin-import": "^2.30.0",
-    "eslint-plugin-jsdoc": "^35.5.1",
+    "eslint-plugin-jsdoc": "^62.5.0",
     "eslint-plugin-prettier": "^5.2.1",
     "glob": "7.1.7",
     "import-meta-resolve": "^4.1.0",
-    "prettier": "^3.3.3",
+    "prettier": "^3.8.1",
     "ses": "^1.14.0",
     "stylus": "^0.62.0",
     "vitepress": "1.3.4"
@@ -127,6 +127,7 @@
       "jsdoc/require-param-description": "off",
       "jsdoc/require-returns": "off",
       "jsdoc/require-returns-description": "off",
+      "jsdoc/tag-lines": "off",
       "import/extensions": [
         "error",
         "always"
@@ -146,5 +147,8 @@
     "trailingComma": "all",
     "arrowParens": "avoid",
     "singleQuote": true
+  },
+  "resolutions": {
+    "better-sqlite3": "^10.0.1"
   }
 }

snippets/contract-format.js

@@ -3,13 +3,15 @@
 // Checks the types as defined in JSDoc comments
 
 // Add imports here
+/**
+ * @import { ContractStartFn } from '@agoric/zoe';
+ */
 
 // Optional: you may wish to use the Zoe helpers in
 // @agoric/zoe/src/contractSupport/index.js
 import { swap as _ } from '@agoric/zoe/src/contractSupport/index.js';
 
 // Import the Zoe types
-import '@agoric/zoe/exported.js';
 
 /**
  * [Contract Description Here]

snippets/test-marshal.js

@@ -173,7 +173,10 @@ test.serial(
   },
 );
 
-/** @typedef {import('@endo/pass-style').Remotable} Brand */
+/**
+ * @import { Remotable } from '@agoric/internal';
+ */
+/** @typedef {Remotable} Brand */
 
 /**
  * The Agoric Board is a well-known name service that issues

snippets/tools/setupBasicMints.js

@@ -22,7 +22,7 @@ export const setup = () => {
   const { admin: fakeVatAdmin, vatAdminState } = makeFakeVatAdmin();
   const zoe = makeZoeForTest(fakeVatAdmin);
 
-  /** @type {<K extends AssetKind>(brand: Brand<K>) => (value: any) => Amount<K>} */
+  /** @type {(brand: Brand<'nat'>) => (value: bigint) => Amount<'nat'>} */
   const makeSimpleMake = brand => value => AmountMath.make(brand, value);
 
   const result = {

snippets/tools/zcfTesterContract.js

@@ -1,6 +1,8 @@
 // @ts-check
 
-import '@agoric/zoe/exported.js';
+/**
+ * @import { ContractStartFn } from '@agoric/zoe';
+ */
 
 /**
  * Tests ZCF

snippets/zoe/contracts/test-callSpread.js

@@ -5,7 +5,6 @@ import url from 'url';
 import { resolve as importMetaResolve } from 'import-meta-resolve';
 import bundleSource from '@endo/bundle-source';
 import { E } from '@endo/eventual-send';
-import '@agoric/zoe/exported.js';
 import buildManualTimer from '@agoric/zoe/tools/manualTimer.js';
 import { AmountMath } from '@agoric/ertp';
 

snippets/zoe/src/offer-up.contract.js

@@ -5,8 +5,10 @@
 import { Far } from '@endo/far';
 import { M, getCopyBagEntries } from '@endo/patterns';
 import { AssetKind } from '@agoric/ertp/src/amountMath.js';
-import { atomicRearrange } from '@agoric/zoe/src/contractSupport/atomicTransfer.js';
-import '@agoric/zoe/exported.js';
+/**
+ * @import { Amount } from '@agoric/ertp';
+ * @import { OfferHandler, ZCF } from '@agoric/zoe';
+ */
 
 const { Fail, quote: q } = assert;
 
@@ -56,8 +58,7 @@ export const start = async zcf => {
       Fail`max ${q(maxItems)} items allowed: ${q(want.Items)}`;
 
     const newItems = itemMint.mintGains(want);
-    atomicRearrange(
-      zcf,
+    zcf.atomicRearrange(
       harden([
         // price from buyer to proceeds
         [buyerSeat, proceeds, { Price: tradePrice }],