feat: cleanup orch zones and API plumbing (#9800)

Cleaned up version of orchestration plumbing fixes

* make an orchestrator per flow invocation
* fix zone arch, e.g., so orch fns default to `contract.orchestration`
* support nested orch zones via `makeOrchestrationTools`
* move `asyncFlowAdmin` out of orchestration plumbing
* encapsulate `prepareOrchestratorKit` within `orchestrator.js` and only expose `prepareOrchestrator`

closes: #9792

packages/orchestration/src/exos/orchestrator.js

@@ -1,5 +1,6 @@
 /** @file ChainAccount exo */
 import { AmountShape } from '@agoric/ertp';
+import { pickFacet } from '@agoric/vat-data';
 import { makeTracer } from '@agoric/internal';
 import { Shape as NetworkShape } from '@agoric/network';
 import { Fail, q } from '@endo/errors';
@@ -58,7 +59,7 @@ export const OrchestratorI = M.interface('Orchestrator', {
  *   zcf: ZCF;
  * }} powers
  */
-export const prepareOrchestratorKit = (
+const prepareOrchestratorKit = (
   zone,
   {
     chainHub,
@@ -161,6 +162,29 @@ export const prepareOrchestratorKit = (
     },
   );
 harden(prepareOrchestratorKit);
+
+/**
+ * @param {Zone} zone
+ * @param {{
+ *   asyncFlowTools: AsyncFlowTools;
+ *   chainHub: ChainHub;
+ *   localchain: Remote<LocalChain>;
+ *   chainByName: MapStore<string, HostInterface<Chain>>;
+ *   makeRecorderKit: MakeRecorderKit;
+ *   makeLocalChainFacade: MakeLocalChainFacade;
+ *   makeRemoteChainFacade: MakeRemoteChainFacade;
+ *   orchestrationService: Remote<CosmosInterchainService>;
+ *   storageNode: Remote<StorageNode>;
+ *   timerService: Remote<TimerService>;
+ *   vowTools: VowTools;
+ *   zcf: ZCF;
+ * }} powers
+ */
+export const prepareOrchestrator = (zone, powers) => {
+  const makeOrchestratorKit = prepareOrchestratorKit(zone, powers);
+  return pickFacet(makeOrchestratorKit, 'orchestrator');
+};
+
 /**
  * Host side of the Orchestrator interface. (Methods return vows instead of
  * promises as the interface within the guest function.)

packages/orchestration/src/facade.js

@@ -63,7 +63,7 @@ export const makeOrchestrationFacade = ({
     asyncFlowTools,
   });
 
-  const { prepareEndowment, asyncFlow, adminAsyncFlow } = asyncFlowTools;
+  const { prepareEndowment, asyncFlow } = asyncFlowTools;
 
   /**
    * @template HC - host context
@@ -76,21 +76,19 @@ export const makeOrchestrationFacade = ({
    */
   const orchestrate = (durableName, hostCtx, guestFn) => {
     const subZone = zone.subZone(durableName);
-
-    const hostOrc = makeOrchestrator();
-
-    const [wrappedOrc, wrappedCtx] = prepareEndowment(subZone, 'endowments', [
-      hostOrc,
-      hostCtx,
-    ]);
-
+    const [wrappedCtx] = prepareEndowment(subZone, 'endowments', [hostCtx]);
     const hostFn = asyncFlow(subZone, 'asyncFlow', guestFn);
 
     // cast because return could be arbitrary subtype
     const orcFn = /** @type {HostForGuest<GF>} */ (
-      (...args) => hostFn(wrappedOrc, wrappedCtx, ...args)
+      (...args) => {
+        // each invocation gets a new orchestrator
+        const hostOrc = makeOrchestrator();
+        // TODO: why are the types showing the guest types for arguments?
+        // @ts-expect-error XXX fix broken types
+        return hostFn(hostOrc, wrappedCtx, ...args);
+      }
     );
-
     return harden(orcFn);
   };
 
@@ -119,7 +117,6 @@ export const makeOrchestrationFacade = ({
     );
 
   return harden({
-    adminAsyncFlow,
     orchestrate,
     orchestrateAll,
   });

packages/orchestration/src/utils/start-helper.js

@@ -1,13 +1,12 @@
 import { prepareAsyncFlowTools } from '@agoric/async-flow';
-import { pickFacet } from '@agoric/vat-data';
 import { prepareVowTools } from '@agoric/vow';
 import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport/recorder.js';
 import { makeDurableZone } from '@agoric/zone/durable.js';
 import { makeChainHub } from '../exos/chain-hub.js';
 import { prepareCosmosOrchestrationAccount } from '../exos/cosmos-orchestration-account.js';
 import { prepareLocalChainFacade } from '../exos/local-chain-facade.js';
 import { prepareLocalOrchestrationAccountKit } from '../exos/local-orchestration-account.js';
-import { prepareOrchestratorKit } from '../exos/orchestrator.js';
+import { prepareOrchestrator } from '../exos/orchestrator.js';
 import { prepareRemoteChainFacade } from '../exos/remote-chain-facade.js';
 import { makeOrchestrationFacade } from '../facade.js';
 import { makeZoeTools } from './zoe-tools.js';
@@ -58,12 +57,16 @@ export const provideOrchestration = (
   const zones = (() => {
     const zone = makeDurableZone(baggage);
     return {
+      /** system names for async flow */
       asyncFlow: zone.subZone('asyncFlow'),
-      /** for contract-provided names */
-      contract: zone.subZone('contract'),
+      /** system names for orchestration implementation */
       orchestration: zone.subZone('orchestration'),
+      /** system names for vows */
       vows: zone.subZone('vows'),
+      /** system names for zoe */
       zoe: zone.subZone('zoe'),
+      /** contract-provided names, and subzones */
+      contract: zone.subZone('contract'),
     };
   })();
 
@@ -116,7 +119,7 @@ export const provideOrchestration = (
 
   const chainByName = zones.orchestration.mapStore('chainName');
 
-  const makeOrchestratorKit = prepareOrchestratorKit(zones.orchestration, {
+  const makeOrchestrator = prepareOrchestrator(zones.orchestration, {
     asyncFlowTools,
     chainHub,
     localchain: remotePowers.localchain,
@@ -131,21 +134,35 @@ export const provideOrchestration = (
     zcf,
   });
 
-  const makeOrchestrator = pickFacet(makeOrchestratorKit, 'orchestrator');
-
-  const facade = makeOrchestrationFacade({
-    zcf,
-    zone: zones.orchestration,
-    makeRecorderKit,
-    makeOrchestrator,
-    asyncFlowTools,
-    vowTools,
-    ...remotePowers,
-  });
+  /**
+   * Create orchestrate functions in a specific zone, instead of the default
+   * `contract.orchestration` zone. This is used for modules that add their own
+   * orchestration functions (e.g., a Portfolio with orchestration flows for
+   * continuing offers)
+   *
+   * @param {Zone} zone
+   */
+  const makeOrchestrateKit = zone =>
+    makeOrchestrationFacade({
+      zone,
+      zcf,
+      makeRecorderKit,
+      makeOrchestrator,
+      asyncFlowTools,
+      vowTools,
+      ...remotePowers,
+    });
+
+  // Create orchestrate functions for the default `contract.orchestration` zone
+  const defaultOrchestrateKit = makeOrchestrateKit(
+    zones.contract.subZone('orchestration'),
+  );
   return {
-    ...facade,
+    ...defaultOrchestrateKit,
+    makeOrchestrateKit,
     chainHub,
     vowTools,
+    asyncFlowTools,
     zoeTools,
     zone: zones.contract,
   };

packages/orchestration/test/examples/snapshots/sendAnywhere.test.ts.md

@@ -29,6 +29,21 @@ Generated by [AVA](https://avajs.dev).
         'ChainHub Admin_singleton': 'Alleged: ChainHub Admin',
         'Send PF_kindHandle': 'Alleged: kind',
         'Send PF_singleton': 'Alleged: Send PF',
+        orchestration: {
+          sendIt: {
+            asyncFlow_kindHandle: 'Alleged: kind',
+            endowments: {
+              0: {
+                contractState_kindHandle: 'Alleged: kind',
+                contractState_singleton: 'Alleged: contractState',
+                findBrandInVBank_kindHandle: 'Alleged: kind',
+                findBrandInVBank_singleton: 'Alleged: findBrandInVBank',
+                localTransfer_kindHandle: 'Alleged: kind',
+                localTransfer_singleton: 'Alleged: localTransfer',
+              },
+            },
+          },
+        },
       },
       orchestration: {
         'Cosmos Orchestration Account Holder_kindHandle': 'Alleged: kind',
@@ -37,19 +52,6 @@ Generated by [AVA](https://avajs.dev).
         Orchestrator_kindHandle: 'Alleged: kind',
         RemoteChainFacade_kindHandle: 'Alleged: kind',
         chainName: {},
-        sendIt: {
-          asyncFlow_kindHandle: 'Alleged: kind',
-          endowments: {
-            1: {
-              contractState_kindHandle: 'Alleged: kind',
-              contractState_singleton: 'Alleged: contractState',
-              findBrandInVBank_kindHandle: 'Alleged: kind',
-              findBrandInVBank_singleton: 'Alleged: findBrandInVBank',
-              localTransfer_kindHandle: 'Alleged: kind',
-              localTransfer_singleton: 'Alleged: localTransfer',
-            },
-          },
-        },
       },
       vows: {
         PromiseWatcher_kindHandle: 'Alleged: kind',

packages/orchestration/test/examples/snapshots/unbondExample.test.ts.md

@@ -25,14 +25,16 @@ Generated by [AVA](https://avajs.dev).
         unwrapMap: 'Alleged: weakMapStore',
       },
       contract: {
+        orchestration: {
+          LSTTia: {
+            asyncFlow_kindHandle: 'Alleged: kind',
+          },
+        },
         publicFacet_kindHandle: 'Alleged: kind',
         publicFacet_singleton: 'Alleged: publicFacet',
       },
       orchestration: {
         'Cosmos Orchestration Account Holder_kindHandle': 'Alleged: kind',
-        LSTTia: {
-          asyncFlow_kindHandle: 'Alleged: kind',
-        },
         'Local Orchestration Account Kit_kindHandle': 'Alleged: kind',
         LocalChainFacade_kindHandle: 'Alleged: kind',
         Orchestrator_kindHandle: 'Alleged: kind',