build orc docs (#9291)

no ticket

## Description

Include `@agoric/orchestration` in the typedoc so we can retire
https://github.com/agoric-labs/orchestration-api-spec/

Also cleans up file naming and locations

### Security Considerations

<!-- 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

<!-- 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

<!-- 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

<!-- 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

<!-- What aspects of this PR are relevant to upgrading live production
systems, and how should they be addressed? -->

packages/boot/test/bootstrapTests/test-orchestration.ts

@@ -4,7 +4,7 @@ import type { TestFn } from 'ava';
 
 import { Fail } from '@agoric/assert';
 import { AmountMath } from '@agoric/ertp';
-import type { start as stakeBldStart } from '@agoric/orchestration/src/contracts/stakeBld.contract.js';
+import type { start as stakeBldStart } from '@agoric/orchestration/src/examples/stakeBld.contract.js';
 import type { Instance } from '@agoric/zoe/src/zoeService/utils.js';
 import { M, matches } from '@endo/patterns';
 import { makeWalletFactoryContext } from './walletFactory.ts';

packages/builders/scripts/orchestration/init-stakeAtom.js

@@ -16,9 +16,7 @@ export const defaultProposalBuilder = async (
       {
         installKeys: {
           stakeAtom: publishRef(
-            install(
-              '@agoric/orchestration/src/contracts/stakeAtom.contract.js',
-            ),
+            install('@agoric/orchestration/src/examples/stakeAtom.contract.js'),
           ),
         },
         hostConnectionId,

packages/builders/scripts/orchestration/init-stakeBld.js

@@ -10,7 +10,7 @@ export const defaultProposalBuilder = async ({ publishRef, install }) =>
       {
         installKeys: {
           stakeBld: publishRef(
-            install('@agoric/orchestration/src/contracts/stakeBld.contract.js'),
+            install('@agoric/orchestration/src/examples/stakeBld.contract.js'),
           ),
         },
       },

packages/orchestration/README.md

@@ -1,4 +1,5 @@
 # Orchestration
 
+Build feature-rich applications that can orchestrate assets and services across the interchain.
 
-Interface for Cosmos Interchain Accounts [(ICS-27)](https://github.com/cosmos/ibc/blob/main/spec/app/ics-027-interchain-accounts/README.md).
+Usage examples can be found under [src/examples](https://github.com/Agoric/agoric-sdk/tree/master/packages/orchestration/src/examples). They are exported for integration testing with other packages.

packages/orchestration/src/contracts/stakeAtom.contract.js → packages/orchestration/src/examples/stakeAtom.contract.js

@@ -7,7 +7,7 @@ import { makeDurableZone } from '@agoric/zone/durable.js';
 import { V as E } from '@agoric/vat-data/vow.js';
 import { M } from '@endo/patterns';
 import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport';
-import { prepareStakingAccountHolder } from './stakingAccountHolder.js';
+import { prepareStakingAccountKit } from '../exos/stakingAccountKit.js';
 
 const trace = makeTracer('StakeAtom');
 /**
@@ -41,7 +41,7 @@ export const start = async (zcf, privateArgs, baggage) => {
 
   const { makeRecorderKit } = prepareRecorderKitMakers(baggage, marshaller);
 
-  const makeStakingAccountHolder = prepareStakingAccountHolder(
+  const makeStakingAccountKit = prepareStakingAccountKit(
     baggage,
     makeRecorderKit,
     zcf,
@@ -54,7 +54,7 @@ export const start = async (zcf, privateArgs, baggage) => {
     );
     const accountAddress = await E(account).getAccountAddress();
     trace('account address', accountAddress);
-    const { holder, invitationMakers } = makeStakingAccountHolder(
+    const { holder, invitationMakers } = makeStakingAccountKit(
       account,
       storageNode,
       accountAddress,

packages/orchestration/src/contracts/stakeBld.contract.js → packages/orchestration/src/examples/stakeBld.contract.js

@@ -10,7 +10,7 @@ import { M } from '@endo/patterns';
 import { E } from '@endo/far';
 import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport/recorder.js';
 import { atomicTransfer } from '@agoric/zoe/src/contractSupport/atomicTransfer.js';
-import { prepareAccountHolder } from './localchainAccountHolder.js';
+import { prepareLocalchainAccountKit } from '../exos/localchainAccountKit.js';
 
 const trace = makeTracer('StakeBld');
 
@@ -35,7 +35,7 @@ export const start = async (zcf, privateArgs, baggage) => {
     baggage,
     privateArgs.marshaller,
   );
-  const makeAccountHolderKit = prepareAccountHolder(
+  const makeLocalchainAccountKit = prepareLocalchainAccountKit(
     baggage,
     makeRecorderKit,
     zcf,
@@ -56,7 +56,7 @@ export const start = async (zcf, privateArgs, baggage) => {
           await E(lcaSeatKit.userSeat).tryExit();
           trace('awaiting payouts');
           const payouts = await E(lcaSeatKit.userSeat).getPayouts();
-          const { holder, invitationMakers } = makeAccountHolderKit(
+          const { holder, invitationMakers } = makeLocalchainAccountKit(
             account,
             privateArgs.storageNode,
           );

packages/orchestration/src/contracts/localchainAccountHolder.js → packages/orchestration/src/exos/localchainAccountKit.js

@@ -40,7 +40,7 @@ const PUBLIC_TOPICS = {
  * @param {import('@agoric/zoe/src/contractSupport/recorder.js').MakeRecorderKit} makeRecorderKit
  * @param {ZCF} zcf
  */
-export const prepareAccountHolder = (baggage, makeRecorderKit, zcf) => {
+export const prepareLocalchainAccountKit = (baggage, makeRecorderKit, zcf) => {
   const makeAccountHolderKit = prepareExoClassKit(
     baggage,
     'Account Holder',
@@ -152,3 +152,4 @@ export const prepareAccountHolder = (baggage, makeRecorderKit, zcf) => {
   );
   return makeAccountHolderKit;
 };
+/** @typedef {ReturnType<ReturnType<typeof prepareLocalchainAccountKit>>} LocalchainAccountKit */

packages/orchestration/src/contracts/stakingAccountHolder.js → packages/orchestration/src/exos/stakingAccountKit.js

@@ -54,8 +54,8 @@ const PUBLIC_TOPICS = {
  * @param {MakeRecorderKit} makeRecorderKit
  * @param {ZCF} zcf
  */
-export const prepareStakingAccountHolder = (baggage, makeRecorderKit, zcf) => {
-  const makeAccountHolderKit = prepareExoClassKit(
+export const prepareStakingAccountKit = (baggage, makeRecorderKit, zcf) => {
+  const makeStakingAccountKit = prepareExoClassKit(
     baggage,
     'Staking Account Holder',
     {
@@ -193,5 +193,6 @@ export const prepareStakingAccountHolder = (baggage, makeRecorderKit, zcf) => {
       },
     },
   );
-  return makeAccountHolderKit;
+  return makeStakingAccountKit;
 };
+/** @typedef {ReturnType<ReturnType<typeof prepareStakingAccountKit>>} StakingAccountKit */

packages/orchestration/src/proposals/start-stakeAtom.js

@@ -3,12 +3,12 @@ import { makeTracer } from '@agoric/internal';
 import { makeStorageNodeChild } from '@agoric/internal/src/lib-chainStorage.js';
 import { E } from '@endo/far';
 
-/** @import { StakeAtomSF,  StakeAtomTerms} from '../contracts/stakeAtom.contract' */
+/** @import { StakeAtomSF,  StakeAtomTerms} from '../examples/stakeAtom.contract' */
 
 const trace = makeTracer('StartStakeAtom', true);
 
 /**
- * @param {BootstrapPowers & { installation: {consume: {stakeAtom: Installation<import('../contracts/stakeAtom.contract.js').start>}}}} powers
+ * @param {BootstrapPowers & { installation: {consume: {stakeAtom: Installation<import('../examples/stakeAtom.contract.js').start>}}}} powers
  * @param {{options: StakeAtomTerms }} options
  */
 export const startStakeAtom = async (

packages/orchestration/src/proposals/start-stakeBld.js

@@ -6,7 +6,7 @@ import { E } from '@endo/far';
 const trace = makeTracer('StartStakeBld', true);
 
 /**
- * @param {BootstrapPowers & {installation: {consume: {stakeBld: Installation<import('../contracts/stakeBld.contract.js').start>}}}} powers
+ * @param {BootstrapPowers & {installation: {consume: {stakeBld: Installation<import('../../test/examples/stakeBld.contract.js').start>}}}} powers
  */
 export const startStakeBld = async ({
   consume: { board, chainStorage, localchain, startUpgradable },
@@ -29,7 +29,7 @@ export const startStakeBld = async ({
   const marshaller = await E(board).getPublishingMarshaller();
 
   // FIXME this isn't detecting missing privateArgs
-  /** @type {StartUpgradableOpts<import('../contracts/stakeBld.contract.js').start>} */
+  /** @type {StartUpgradableOpts<import('../../test/examples/stakeBld.contract.js').start>} */
   const startOpts = {
     label: 'stakeBld',
     installation: stakeBld,

packages/orchestration/typedoc.json

@@ -2,5 +2,7 @@
   "extends": [
     "../../typedoc.base.json"
   ],
-  "entryPoints": []
+  "entryPoints": [
+    "index.js",
+  ]
 }