docs: a set of diagrams on Zoe and Zcf datastores and initialization (#…

…6389)

* docs: a set of diagrams on Zoe and Zcf datastores and initialization

refs: #4383

The datastore diagram was created in Miro:
https://miro.com/app/board/uXjVPR6j4Nc=/?share_link_id=559329933746

The others are .puml rendered to png.

These diagrams show the state of Zoe and ZCF as of 2022/10/1. I expect
to update them as I finish the conversion to durability.

The datastore diagram shows which objects and stores are accessible to
Zoe or to ZCF, and which are shared.

The sequence diagrams show the order in which the various objects are
created, passed between the vats, and when promises are resolved.

* docs: updates to Zoe-ZCF dataStores miro diagram

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

packages/zoe/docs/ZcfDataInitialization.puml

@@ -0,0 +1,50 @@
+@startuml Zoe/ZCF dataStore initialization
+
+actor bootstrap
+
+box Zoe Vat
+participant ZoeService
+participant StartInstance
+participant InstanceStorageManager
+end box
+
+box Zcf Vat
+participant vatRoot
+participant ZcfZygote
+participant contract
+end box
+
+bootstrap -> ZoeService : install(bundle)
+bootstrap <- ZoeService : <font color=gray><size:12>installation
+bootstrap -> ZoeService : startInstance(installation)
+ZoeService -> StartInstance : startInstance(\ninstallation, \nissuerKeywordRecord\nterms, privateArgs)
+StartInstance -> StartInstance : initialize instance state
+StartInstance -> InstanceStorageManager : makeInstanceStorageManager
+InstanceStorageManager -> vatRoot : createZcfVat(bundle)
+note right
+{ zoeService, invitationIssuer } = vatParameters;
+end note
+
+vatRoot -> ZcfZygote : makeZcfZygote(powers, zoeService,\ninvitationIssuer, bundle, baggage)
+ZcfZygote -> ZcfZygote : createSeatManager()
+ZcfZygote -> ZcfZygote : makeInstanceRecordStorage()
+ZcfZygote -> ZcfZygote : makeEmptySeatKit = () => {...}
+ZcfZygote -> ZcfZygote : makeHandleOfferObj = (...) => {...}
+ZcfZygote -> contract : evaluateContract(bundle)
+ZcfZygote /- contract : <font color=gray><size:12>start
+
+vatRoot /- ZcfZygote : <font color=gray><size:12>zcfZygote
+InstanceStorageManager /- vatRoot : <font color=gray><size:12>root
+StartInstance /- InstanceStorageManager : <font color=gray><size:12>root, adminNode, getters
+StartInstance -> vatRoot : startZcf(zoeInstanceAdmin,\ninstanceRecord,\nissuerStorage, privateArgs)
+vatRoot -> ZcfZygote : startContract(zoeInstanceAdmin,\ninstanceRecord,\nissuerStorage, privateArgs)
+ZcfZygote -> ZcfZygote : set up instance state
+ZcfZygote -> contract : start(zcf, privateArgs,...)
+ZcfZygote /- contract : <font color=gray><size:12>publicFacet, creatorFacet, handleOfferObj
+StartInstance /- ZcfZygote : <font color=gray><size:12>publicFacet, creatorFacet, handleOfferObj
+
+note left
+resolve facet & handleOfferObj promises
+end note
+
+@enduml

packages/zoe/docs/ZoeDataInitialization.puml

@@ -0,0 +1,37 @@
+@startuml Zoe/ZCF dataStore initialization
+
+box Zoe startup
+participant bootstrap
+participant Zoe
+participant ZoeStorageManager
+collections InstanceAdminStorage
+participant startInstance
+
+end box
+
+bootstrap -> Zoe: makeZoeKit(...)
+Zoe -> ZoeStorageManager : makeZoeStorageManager()
+ZoeStorageManager -> ZoeStorageManager : provideIssuerStorage()
+ZoeStorageManager -> ZoeStorageManager : makeEscrowStorage()
+ZoeStorageManager -> ZoeStorageManager : vivifyInvitationKit()
+ZoeStorageManager -> InstanceAdminStorage : makeInstanceAdminStorage()
+InstanceAdminStorage -> InstanceAdminStorage : instanceToInstanceAdmin
+ZoeStorageManager /- InstanceAdminStorage : <font color=gray><size:12>getters..., \n<font color=gray><size:12>initInstanceAdmin
+ZoeStorageManager -> ZoeStorageManager : makeInstallationStorage()
+Zoe /-- ZoeStorageManager : <font color=gray><size:12>{makeZoeInstanceStorageManager,\n<font color=gray><size:12>getters, invitationIssuer}
+Zoe -> startInstance : makeStartInstance(makeZoeInstanceStorageManager, <bundle details>, ...)
+Zoe /- startInstance : <font color=gray><size:12>startInstance
+Zoe -> Zoe : makeOfferMethod()
+
+note right
+When Zoe starts up, it initializes datastores that hold data generic to
+all contracts. It creates InstanceAdminStorage which will hold
+instanceAdmins that have data for individual instances.
+startInstance() is used for creating new instances. offer() is used to
+exercise invitations.
+end note
+
+Zoe -> Zoe : makeZoeService(offer)
+Zoe -\ bootstrap : <font color=gray><size:12>ZoeService
+
+@enduml

packages/zoe/docs/offers+invitations+seats.puml

@@ -0,0 +1,56 @@
+@startuml Zoe/ZCF: Invitations, Offers, Seats
+
+actor user
+participant "Zoe\n<size:12>(shared state)" as Zoe
+participant "Zoe\n<size:12>(instance state)" as ZoeInstance
+participant ZCF
+participant contract
+
+== making invitations ==
+
+contract -> ZCF : makeInvitation(handler, desc, ...)
+ZCF -> ZCF : handle = storeOfferHandler(handler)
+ZCF -> Zoe : makeInvitation(handle,desc,...)
+ZCF /- Zoe : <font color=gray><size:12>invitation
+contract /- ZCF : <font color=gray><size:12>invitation
+note bottom
+The invitation might be returned via a public facet,
+or from a method on a seat, or some other way.
+end note
+
+== making an offer ==
+
+user -> Zoe : E(zoe).offer(invitation,\nproposal, payment, ...)
+Zoe -> Zoe : find instance from invitation\nburn invitation\nvalidate acceptingOffers()\nclean proposal\ndeposit Payments
+Zoe -> ZoeInstance : makeUserSeat()
+ZoeInstance -> ZoeInstance :make:\n  offefResultPromiseKit\n  exitObjPromiseKit\n  seatHandle
+ZoeInstance -> ZoeInstance : { userSeat, zoeSeatAdmin } =\n  makeSeatAdminKit(alloc, proposal, promises, ...)
+ZoeInstance -> ZoeInstance : store zoeSeatAdmin
+ZoeInstance -> ZCF : handleOffer(invitation, seatData)
+ZCF -> ZCF : makeZcfSeat()
+ZCF -> contract : handler(zcfSeat, offerArgs)
+contract -> contract : whatever
+ZCF -> ZCF : make offerResultPromiseKit
+ZCF -> ZCF : exitObj = makeExitObj()
+ZoeInstance /- ZCF : <font color=gray><size:12>offerResultPromise, exitObj
+user /- ZoeInstance : <font color=gray><size:12>userSeat
+ZCF /- contract : <font color=gray><size:12>offerResult, exitObj
+ZCF -> ZCF : wait for result, then\n  resolve promise or fail seat
+ZCF -> ZoeInstance : <font color=gray><size:12>promise resolution
+ZoeInstance -> ZoeInstance : resolvePromises or throw()
+
+== creating empty seats ==
+
+contract -> ZCF : makeEmptySeatKit()
+ZCF -> ZCF : promise = makePromiseKit
+ZCF -> ZCF : seatHandle = makeSeatHandle()
+ZCF -> ZCF : makeZcfSeat({}, {}, seatHandle)
+ZCF -> ZCF : exitObj = makeExitObj({}, handle)
+ZCF -> ZoeInstance : makeNoEscrowSeatKit({}, {}, exitObj, seatHandle)
+ZCF -> contract : <font color=gray><size:12>{ zcfSeat, userSeat: promise }
+ZoeInstance -> ZoeInstance : { userSeat, notifier, zoeSeatAdmin } =\n  makeSeatAdminKit(alloc, proposal,\n  promises, ...)
+ZoeInstance -> ZoeInstance : store zoeSeatAdmin
+ZCF /- ZoeInstance : <font color=gray><size:12>useSeat, notifier
+ZCF -> ZCF : <font color=gray>resolve userSeat promise
+
+@enduml