Bind GraphQL API to Holochain API

Following #7, implement resolver functions in query & type defs, but only as much as is necessary to service GFD app(s).

I'm referring to https://github.com/holo-rea/holo-rea-proto/blob/feature/graphql-binding/src/graphql-adapter/src/types.ts throughout here.

// :TODO: check date field compat with ValueNetwork API

HoloREA uses integer dates right now. I typedef'd this everywhere I could, so theoretically I could change it. Is there any reason to give up that convenience for calculating end dates, sorting, and comparing without converting? It seems like converting it for the user to check out happens a lot less often.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L55

re: Actions, we are not using integer constants as identifiers anymore. Holochain uses hashes and JSON. For the actions defined in this file. you can get the fixture hashes like so:

const fixtures = await events.getFixtures({});
export const Action = new GraphQLEnumType({
  name: 'Action',
  values: {
    ADJUST: fixtures.Action.adjust,
    CONSUME: fixtures.Action.consume,
    GIVE: fixtures.Action.give,
    PRODUCE: fixtures.Action.produce,
    TAKE: fixtures.Action.receive,
  }
})

The rest, NONE, ACCEPT, CITE, IMPROVE, and WORK are not implemented yet. NONE I don't think needs a fixture; null or an empty hash can serve the same purpose, but if one doesn't find an appropriate action for one's event, it is easy enough to make a new one:

const STRANGE_ACTION = await events.createAction({ name: "strangeAction", behavior: "+" });

And that brings me to the idea that maybe a GraphQLEnumType is not the right binding for Actions or other types of classifications in HoloREA. Everything is now extensible, and off the top of my head, the only really enum-ish thing in there is the Action's behavior property, which can be '+', '-', or '0'.

Here's a trick for the classifications that are nominal right now: there is nothing wrong with trying to create it from scratch. A TransferClassification called "purchase", for example, has only one property, name, and you know the value. No matter how many times you events.createTransferClass({ name: "purchase" }), you will always get the same hash because the value is exactly the same. It's like an anchor. If there is a doubt about whether a classification exists, just create it for yourself using the exact VF name without the namespace. If it exists already, no foul. If it didn't before, now it does.

Note that I goofed on the name property in all cases except ProcessClassification. It should be label according to VF, but it's currently name in Action, TransferClassification, and ResourceClassification. You can fix that with GraphQL for the GFD UI, right?

As for the rest, can you clarify whether they are increments or decrements (consistent with VF)? My guess would have WORK as an increment, maybe CITE and ACCEPT. and IMPROVE probably a 0. Also, do the names map exactly to VF? I will add them to the fixtures once I figure that out one way or another.

Final note on Actions: the GFD scenario (https://github.com/holo-rea/holo-rea-proto/blob/master/build/test/src/scenario.ts) fetches all of the existing fixtures and defines two new ones:

pick: { name: "pick", behavior: '+' } as in picking apples.
gather: { name: "gather", behavior: '+' } as in gathering coffee beans.

All of them are found in the structure produced by ready() by name in scenario.actions.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L72

EconomicResourceCategory is not a thing in HoloREA right now. We will want something like it in rusty-chain, but I didn't want to jump the gun on VF defining it.

EconomicResourceProcessCategory: also not a thing.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L96

Re: Units. Units are strings in HoloREA. It is possible to make complicated units like Joules ("kg*m^2*s^-2") as described in https://github.com/holo-rea/holo-rea-proto/blob/master/docs/web-api.md#quantityvalue-struct. I'm on the fence about how that should evolve because of how vastly different currencies are from real units that have existing ontologies; better make an issue for it sooner or later.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L107

Re: QuantityValue. HoloREA uses quantity instead of numericValue. I'm reasonably certain I got that from VF.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L116

Re: Notifications: Not a thing. I'm not expecting to build them into the core HoloREA app because it isn't in REA or VF. That's for another module.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L134

ResourceClassification, there are no categories now. unit is now defaultUnits to allow e.g. pounds and kilograms to coexist for a resource type. See https://github.com/holo-rea/holo-rea-proto/blob/master/docs/web-api.md#resourceclassification-class-extends-vfobject

The GFD scenario defines apples, (coffee) beans, (brewed) coffee, and (apple) turnovers by name in scenario.types.resource.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L150

ProcessClassification is implemented now. It's just a label property, and its only fixture is a stub currently. See https://github.com/holo-rea/holo-rea-proto/blob/master/docs/web-api.md#processclassification-class-extends-vfobject

The GFD scenario defines brew (coffee) and bake (turnovers) as process classifications, which are found by name in scenario.types.process.

The rest of the items you have commented out here are correct.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L168

Place has a correlate, PhysicalLocation, but it isn't very structured. It's just an array of strings that form a street address. See https://github.com/holo-rea/holo-rea-proto/blob/master/docs/web-api.md#physicallocation-type

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L196

Process is now implemented and used in the GFD scenario. See https://github.com/holo-rea/holo-rea-proto/blob/master/docs/web-api.md#process-class-extends-vfobject

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L199

EconomicResource: as is the case for all HoloREA objects, there is no integer ID (did I read this wrong?). Instead, Holochain and thus HoloREA use hash strings. In addition, the hash is not part of the object itself, because a property whose value is the hash would necessarily change the hash of the object. The GraphQL field, a hash string, should be obtained from the CrudResponse object that wraps the payload data. See https://github.com/holo-rea/holo-rea-proto/blob/master/docs/web-api.md#crudresponset-struct

There is no source for currentLocation at the moment. VF has sketchy definitions for transportation events, and events are how the property would be changed, thus the form it takes here will depend on future VF. There is, however, an owner agent, and agents do have a primaryLocation, if you want to use that.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L240

There are no Exchanges in HoloREA.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L246

There is no Validation in HoloREA in the NRP sense.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L251

AgentRelationship is not defined at all yet in HoloREA.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L254

Agents in HoloREA don't yet have phone or email contacts. ownedEconomicResources is coming along nicely.

https://github.com/holo-rea/holo-rea-proto/blob/d8571bb63d515d774380af85c069c683e4a63de5/src/graphql-adapter/src/types.ts#L412

We don't have notifications.

A few VF comments. But.... these are general comments, if we want to take shortcuts for GFD, or leave GFD as is for simplicity of development, any of these can and should be ignored for now.

NONE I don't think needs a fixture; null or an empty hash can serve the same purpose, but if one doesn't find an appropriate action for one's event, it is easy enough to make a new one:

I think we should ignore NONE, and require an action. I can't remember why I put that into the valuenetwork api, but I don't like it.

And that brings me to the idea that maybe a GraphQLEnumType is not the right binding for Actions or other types of classifications in HoloREA. Everything is now extensible, and off the top of my head, the only really enum-ish thing in there is the Action's behavior property, which can be '+', '-', or '0'.

I agree. In rdf, different structures sometimes make sense given the way it handles properties. In this case, I think an Action class with a property for behavior makes more sense even though it would work to have "increment" or "decrement" as a parent. There will be more properties coming I would guess. I'll try to get that clarified in VF.

Note that I goofed on the name property in all cases except ProcessClassification. It should be label according to VF, but it's currently name in Action, TransferClassification, and ResourceClassification. You can fix that with GraphQL for the GFD UI, right?

This is the fault of a bit of VF documentation churn. What you see in the URL diagram in VF is behind right now. We did make some progress on recipes, which is merged in the source, but not updated in that diagram. They include some of the old "classification" classes. It should look like this: recipe

As for the rest, can you clarify whether they are increments or decrements (consistent with VF)? My guess would have WORK as an increment, maybe CITE and ACCEPT. and IMPROVE probably a 0.

You can find out here what is defined as increment, decrement, or neither. https://github.com/valueflows/valueflows/blob/master/release-doc-in-process/all_vf.TTL#L443 Look at their subproperties.

I'm on the fence about how that should evolve because of how vastly different currencies are from real units that have existing ontologies; better make an issue for it sooner or later.

We are on the fence a bit in VF about units too. Right now we are using QUDT vocabulary for units and for quantities. There are many things not defined yet there and the website is not easy to use. Some of us think we need to use something else but we haven't gotten to researching it yet. In the valuenetwork api, I just used strings, since that is how it is in the backend. That is fine for GFD too.

Related to that, the way QUDT (and therefore VF now) does quantities, is that every property that is a quantity in VF (currentQuantity, affectedQuantity, etc.) is a QuantityValue object, which is made up of a numericValue and a unit. I think VF will always have that basic structure for a quantity, even if we the names might change at some point.

as is the case for all HoloREA objects, there is no integer ID

Yeah, the integer id's in valuenetwork api are implementation specific. In ActivityPub in MoodleNet they decided an interesting thing - they have id and they have localId. Since that linked open data, the id is always the unique URI that will serve up the data for that object, which is standard. And the localId is whatever is implemented (for them an integer given the postgres db, for holochain the hash string I guess). Just food for thought for later.

There is no Validation in HoloREA in the NRP sense.

Probably never will be. May be best to think of the valuenetwork api as VF at a certain stage, some made up VF because it wasn't ready yet, and some implementation specific things that were needed for FairCoop but won't be needed by others necessarily and won't be VF. This is one of the latter.

Re: QuantityValue. HoloREA uses quantity instead of numericValue. I'm reasonably certain I got that from VF.

Related to that, the way QUDT (and therefore VF now) does quantities, is that every property that is a quantity in VF (currentQuantity, affectedQuantity, etc.) is a QuantityValue object, which is made up of a numericValue and a unit. I think VF will always have that basic structure for a quantity, even if we the names might change at some point.

One further point by way of explanation: in the mutations in valuenetwork api, I just used the "sub" properties, where in the queries you will see it come out with the structure described above. Didn't see a better way to do that in graphql, but if there is, I'm interested @pospi ! This must be a common issue in graphql?

There is, however, an owner agent

This is controversial in VF. We haven't decided if a data structure reflecting agent-resource relationships is a good idea - and in any case, it would be derived. (That is how NRP did the data structure. But NRP didn't create/change it based on events, which it really should.) If you are right now figuring that out by the latest transfer @sqykly , that is great. Eventually we'll want to deal with transfers of non-ownership rights, like renting an apartment.

Place has a correlate, PhysicalLocation, but it isn't very structured.

Yeah, Place (or Location or PhysicalLocation) isn't really defined in VF, we hope to just take another vocabulary's definition. If/when we want to do some mapping or similar, we'll need to make some decisions, either in VF or just here.

You've also noticed there isn't a lot of "normal" stuff for Agents, also sort of tbd, in VF we should probably at least recommend another vocabulary. I'm wondering if someone (or we) will want to do an Agent app for holochain, since it seems like the agent-centricity calls for that in some way.

Thanks for these detailed responses all! <3

Hear you both on no integer IDs. I'm under the impression GraphQLID will take a string if you ask it to, and that it has some additional attributes which make indexing on the field value more useful. Will soon find out.

@sqykly-

you can get the fixture hashes like so: [...]

Is there a way to pull these constants out so they can be read without an async call? Ideally these are just string enum types for the caller, right? It doesn't actually look like getFixtures is async, so hopefully I don't have to rewrite anything for this to work. It looks like you're just calling getFixtures(null).Action.Adjust in object initialisation in your code in the same way as I was hoping to be. We should memoize the function though.

Fixture is an interesting name for this that I don't quite grok. Can you elaborate more as to what this means in the context of a key / value hash mapping?

the idea that maybe a GraphQLEnumType is not the right binding for Actions

I think either actions have evolved, or the three of us are conflating the internal details of Actions (your end) vs. external GraphQL API's presentation of them (mine). Or both. I suspect similar logic that you're describing in your implementation exists in NRP, but that it's Python code sitting behind the API server, where the gateway only takes strings of the different action types in order to manage & assign them. That sounds right to me. @fosterlynn probably knows the answer to that?

In other words, under the hood in the DHT zome code; @sqykly's actions are full TypeScript objects with their own hardcoded behaviours and properties. On the client end, all we need to do to reference them is to specify their hash, or more accurately- a named link anchored to that hash (Fixture?).

Are you both with me or am I barking up the wrong tree?

a trick for the classifications

I really like that. We can treat classifications (and other things) as lazily-evaluated memoized functions which push a record to the DHT. Feels clean.

You can fix [the name property] with GraphQL for the GFD UI, right?

Sure, we can rewire attribute names. Seems equivalent effort for me to step in to the DHT code and update the field names, though; and saves us needing to undo hacks later.

EconomicResourceCategory et al

Cool, will comment those out (:

Notifications: Not a thing

Agreed. And I suspect the notifications would be handled rather differently than in a conventional web client / server scenario.

ResourceClassification, there are no categories now

Is this because categories have been phased out in favour of facets?

PhysicalLocation

I'll probably leave this one out for now, it's a bit weird. If anything I thought such a structure would replace or be an option for Place.address?

@fosterlynn:

Should Agent.primaryLocation not be a Place, rather than a string?

There are no Exchanges in HoloREA

I think there's an abstraction worth drawing out here, which also relates to Transfer. These are both just subtypes of EconomicEvent, right? Perhaps other classes we have in GFD are too.

These feel like the same kinds of distinctions as I was talking about above in relation to Actions. Are we just describing types of economic event, which have their own additional logics and fields?

The reason I ask is that if there's no Exchange in HoloREA as yet, it might make sense to add one down the track? It did seem like a useful behaviour to codify.

There is no Validation in HoloREA in the NRP sense.

Is there any opportunity / utility in adding Validation into the core REA app or a satellite helper app? Or is it to be considered "nonstandard FreedomCoop extensions" and left in their hands? Just trying to understand how the divergence should be handled & where / if it should be logged somewhere.

I just used the "sub" properties

You mean like, real sub-properties, or just sub_properties? Because IIRC the way I left it, I had only figured out how to do the latter; and the former is what we really want ideally. Pretty sure we're talking about the same issue. Yes, it's possible- just didn't know enough Python to get there at the time.

I also just noticed @sqykly that QuantityValue has units rather than unit in NRP. Errata, or intended upgrade path?

Ooooh, sorry just re-discovered this.

I think either actions have evolved, or the three of us are conflating the internal details of Actions (your end) vs. external GraphQL API's presentation of them (mine).

For GFD, we can do whatever is easiest/what David expects. The main thing that we need to know about an action is does it increment or decrement the resource, or neither. Right now in VF actions are just properties, which inherit from increment, decrement, or not. We might want to make them have more data in VF, but not decided yet. We can also hard-code that behavior for GFD, fine with me, if that is how it works, or if that is easier.

ResourceClassification, there are no categories now

Is this because categories have been phased out in favour of facets?

No. For GFD, let's just go with a simple classification, implemented however you want. Hard-coding a list is fine. (apples, turnovers, etc.) Will explain VF more when we need to get into more detail. (I think we settled some things after @sqykly started, when we added recipes, so we can elaborate more after GFD.

Should Agent.primaryLocation not be a Place, rather than a string?

Don't need locations for GFD.

(If you're working beyond GFD, then yes it should be a Place. But might be worth just waiting on this.)

I think there's an abstraction worth drawing out here, which also relates to Transfer. These are both just subtypes of EconomicEvent, right? Perhaps other classes we have in GFD are too.

Right now, Transfer is not a subtype of EconomicEvent. Transfer is on the same plane as Process, it contains events - right now give and receive. It's purpose in life is to tie those events together. The reason we have 2 events for "one" transfer is that an event only affects one economic resource, and we have 2 in a transfer (thinking stock resources).

The types of economic events are embodied in Action, we aren't using subtypes or subclasses.

The reason I ask is that if there's no Exchange in HoloREA as yet, it might make sense to add one down the track? It did seem like a useful behaviour to codify.

There is Exchange in VF, called ExchangeAgreement. Don't need it for GFD. The details of the planned exchange are contained in Commitments under the ExchangeAgreement. Not in GFD.

Actually, @pospi maybe you haven't really seen this... https://www.valueflo.ws/specification/diagrams/uml.html. This might answer some questions - but not all, especially in the parts that aren't officially there yet. But please ask too, no problem! :)

Is there any opportunity / utility in adding Validation into the core REA app or a satellite helper app?

Right now, let's consider Validations as non-standard FairCoop things. No need to log.

In general, best to consider the VF published definitions over what you see in that graphql api that we worked on.

I just used the "sub" properties

You mean like, real sub-properties, or just sub_properties?

(This relates to the class QuantityValue, which includes numericValue and unit properties.) So, in the mutations, I used only numericValue and unit in the parameters, then created a QuantityValue when saving.

I'm going to put some graphql "specs" here, until I figure out where something like this should go in the code. Or feel free to take this from here yourself @pospi if it seems usable. Starting with mutations (so I can think about data already being there), will do some queries in the next comment, and update this as needed.

This is what I think is required for GFD, based on the chosen scenario and the current implementation of the schemas created by @sqykly . (Note: some things have changed in VF since David started coding. I'll note them in the graphql, and we can make a decision if to change them now or after GFD.

There are other schemas and fields defined, but this is what it seems to me we need right now. Comments welcome, I could be missing something!

mutation ($token: String!) {
  createProcess(token: $token, name: $name, processClassifiedAsId: $processClassifiedAsId) {
    process {
      id
      name
      processClassifiedAs {
         id
         name
      }
    }
  }
}

mutation ($token: String!) {
  createTransfer(token: $token, name: $name, transferClassifiedAsId: $transferClassifiedAsId) {
    transfer {
      id
      name
      transferClassifiedAs {
        id
        name
      }
    }
  }
}

Notes for process and transfer:

In the above, processClassifiedAs and transferClassifiedAs are optional imo, can discuss.

Fine to add in the other fields already defined in the json schemas if you like.

mutation ($token: String!) {
createEconomicEvent(token: $token, action: $action, start: $start, 
resourceClassifiedAsId: $resourceClassifiedAsId, affectsId: $affectsId, 
affectedNumericValue: $affectedNumericValue, affectedUnitId: $affectedUnitId, 
inputOfId: $inputOfId, outputOfId: $outputOfId, providerId: $providerId, 
receiverId: $receiverId) {
economicEvent {
  id
  action
  start
  inputOf {
    id
    name
  }
  outputOf {
    id
    name
  }
  provider {
    id
    name
  }
  receiver {
    id
    name
  }
  affects {
    id
    resourceClassifiedAs {
      name
    }
  }
  affectedQuantity {
    numericValue
    unit {
      name
    }
  }
}
}
}

Notes for the economic event:

"start" is now "observedTime". Still can just use a formatted date for now, seems fine. Or just leave as "start" too, that's fine.
"unit" can just be a string if you like

Notes for economic resource:

only economic events can create or update resources, at least for GFD (there will need to be other kinds of little-e events that can update things like the note or image, but not needed for GFD)
maybe for now, we can assume that if an economic event references an affected resource (affects), then it needs to find that resource and update it; if not then it needs to create a resource (if it is that kind of event, like a produce)?? I think that will work for all of GFD scenario....

Other required data, to be pre-loaded:

the Agents
Units
TransferClassification(s) (optional)
ProcessClassifications (optional)
ResourceClassifications

Query: Inventory (assuming one page showing all agents with their inventories for demo)

query ($token: String) {
  viewer(token: $token) {
    allAgents {
      id
      name
      ownedEconomicResources {
        id
        resourceClassifiedAs {
          id
          name
        }
        currentQuantity {
          numericValue
          unit {
            name
          }
        }
      }
    }
  }
}

If we want to show agent inventory one at a time, it would be like this:

query ($token: String) {
  viewer(token: $token) {
    agent (id: $id) {
      name
      ownedEconomicResources {
        id
        resourceClassifiedAs {
          id
          name
        }
        currentQuantity {
          numericValue
          unit {
            name
          }
        }
      }
    }
  }
}

The other main query will be the trace from the current state of a resource, thinking about that one.

Queries for selections:

query($token: String) {
  viewer(token: $token) {
    allAgents {
      id
      name
    }
  }
}

query($token: String) {
  viewer(token: $token) {
    allUnits {
      id
      name
    }
  }
}

query ($token: String) {
  viewer(token: $token) {
    allResourceClassifications {
      id
      name
  }
}

(Could also bring back defaultUnit, saw that is there - if it helps out the entry form.)

query ($token: String) {
  viewer(token: $token) {
    allProcessClassifications {
      id
      name
  }
}

query ($token: String) {
  viewer(token: $token) {
    allTransferClassifications {
      id
      name
  }
}

Two issues here.

I think I might not know what "mutation" really means in GraphQL. Is it supposed to affect an instance (e.g. change affectedQuantity) or is it more of a mutation to the system (e.g. creating a new event)?
I'd like to direct your attention, @pospi and @fosterlynn, to the GFD scenario file (https://github.com/holo-rea/holo-rea-proto/blob/dev-gfd/build/test/src/scenario.ts) in case it's been missed. Of particular importance are the interfaces Verbs, Scenario, and Inventory and the class Person. Verbs includes methods very similar to what (I think) you're talking about already:

inventory(whose: Person) => Promise<Inventory> gives you the current QuantityValue of each resource type owned by the agent. If you need the hashes, they are stored in the Person objects in its apples, beans, coffee, and turnovers properties as part of a CrudResponse<EconomicResource>. Note that the objects in Person are not being updated for quantity all the time, so use inventory for that. The Person objects are scenario.al, scenario.bea, and scenario.chloe.
trade(howMany: number, from: Hash<EconomicResource>, to: Hash<EconomicResource>, when = now) => Promise<CrudResponse<Transfer>> is basically good for any of Chloe's exchanges with Al and Bea. It takes two resource hashes, a quantity, and a time. It produces the two events and returns (a Promise for a CrudResponse of) the Transfer object containing both.
pickApples and gatherBeans generate those two events for adding to Al and Bea's inventory from an amount and a time. They are both typed (howMany: number, when: number = now, resource: Hash<EconomicResource> = the right resource) => Promise<CrudResponse<EconomicEvent>>
brewCoffee and bakeTurnovers also take an amount (of coffee/turnovers) and a time. They input the necessary events and return (a Promise for a CrudResponse of) the Process that contains them. Both are typed (amount: number, when: number = now, inputResource: Hash = the right one, ouputResource: Hash = the right one) => Promise<CrudResponse>`.

Does that not cover the "mutations" you're talking about?

I'm also wondering what token is in your code. If it's supposed to be the name of a classification or something, you don't have to (and can't) get it from the server. scenario.types has the classifications for the needed fixtures as well as the scenario-specific classifications in types.resource, types.process, and types.transfer, and scenario.actions has the Action fixtures and scenario-specific actions. The Person objects have the CrudResponse<Agent> as scenario.nameOfPerson.agent, as well as all of their stuff as described above.

In addition, for the resource history bit, you may want to review the web API functions:

traceEvents(Hash<EconomicEvent[]>) => Promise<Hash<EconomicFunction>[]> retrieves a list of Transfers and Processes that had the given events as outputs. see https://github.com/holo-rea/holo-rea-proto/blob/dev-gfd/docs/web-api.md#traceevents-function

traceTransfers(Hash<EconomicFunction>[]) => Promise<Hash<EconomicEvent>[]> retrieves a list of EconomicEvents that were the inputs of the given Transfers and Processes. see https://github.com/holo-rea/holo-rea-proto/blob/dev-gfd/docs/web-api.md#tracetransfers-function

getAffectingEvents({ resource: Hash<EconomicResource> }) => Promise<Hash<EconomicEvent>[]> gets you all events that have affected a single resource. see https://github.com/holo-rea/holo-rea-proto/blob/dev-gfd/docs/web-api.md#getaffectingevents-function

If you need to narrow the lists by start or end date, or sort them by start or end date, there are web API functions that will do that. see https://github.com/holo-rea/holo-rea-proto/blob/dev-gfd/docs/web-api.md#sortevents-function

Finally, eventSubtotals(Hash<EconomicEvent>[]) takes an array like the one you can get from getAffectingEvents() and compiles a report on the complete event history of all resources that were affected by those events. see https://github.com/holo-rea/holo-rea-proto/blob/dev-gfd/docs/web-api.md#eventsubtotals-function

The reason I like the idea of keeping those functions and algorithms on the server is that it has access to all the computed properties and link repos that make things work. You would be duplicating a lot of code just mucking around with computing end dates, adding up QuantityValues, and reading things from the server one at a time, whereas the server has instant access to all of that.

"start" is now "observedTime". Still can just use a formatted date for now, seems fine. Or just leave as "start" too, that's fine.

We are using integer dates currently. You can turn them into a formatted date via the JS Date object

only economic events can create or update resources, at least for GFD (there will need to be other kinds of little-e events that can update things like the note or image, but not needed for GFD)

That's built in.

maybe for now, we can assume that if an economic event references an affected resource (affects), then it needs to find that resource and update it; if not then it needs to create a resource (if it is that kind of event, like a produce)?? I think that will work for all of GFD scenario....

Done. createEvent, resourceCreationEvent, createTransfer (one overload), and createResource have that axiom built in.

the Agents

Done. scenario.al.agent, scenario.bea.agent, scenario.chloe.agent

Units

They're just strings, but if you want to look them up, you can do so with scenario.types.resource.nameOfResource.entry.defaultUnits.

TransferClassification(s) (optional)

All 2 of them are scenario.types.transfer.stub and scenario.types.transfer.trade.

ProcessClassifications (optional)

scenario.types.process has the fixture stub, and the scenario process classifications brew and bake.

ResourceClassifications

scenario.types.resource has the scenario types apples, beans, coffee, and turnovers

The web API docs are here: https://github.com/holo-rea/holo-rea-proto/blob/dev-gfd/docs/web-api.md

I think I might not know what "mutation" really means in GraphQL

It just means create or update or delete, anything not just read. I personally find it annoying when people make up new names for old things, but I suppose it is not bad to have one name for those 3 things. I'm not sure what scope the term is used in.

I'd like to direct your attention, @pospi and @fosterlynn, to the GFD scenario file

Thanks! I thought that was more to run the scenario without the React and graphql pieces... but even then, sounds like it points to an intermediate layer above the schemas? will study it and update graphql accordingly; or ask questions; or figure out how to make the translation, considering @ivanminutillo 's code too. (Sorry I'm pretty behind on the HC stuff, my focus has been on some of our other projects, so I'm playing catch-up.)

I'm also wondering what token is in your code.

Leaving this for @pospi to answer, since I only know one system. In OCP/NRP api, it is a token created from the user credentials that then is sent to the backend for authentication. We don't need any credentials for GFD, true? Pospi, take it from there please....

If you need to narrow the lists by start or end date, or sort them by start or end date, there are web API functions that will do that.

Good, but not needed for GFD.

The reason I like the idea of keeping those functions and algorithms on the server is that it has access to all the computed properties and link repos that make things work.

Makes sense to me. Just trying to think of how to do a graphql thing that accomplishes that. Have a couple ideas, will put into the other issue. But I'll also look at what the graphql would need to call on your side, thanks for short-cutting my search!

This first one's for @fosterlynn's queries (:

Actions: all sorted. @sqykly has seeded them as proper records (with -/+), so that's all fine.

Prepopulated data: Agents is done. Units are hardcoded for GFD to resolve the string / struct dichotomy. And the three types of classifications are all basically done- I haven't finished wiring up ProcessClassifications & TransferClassifications, but David has already populated them and the wiring will be a 15 minute job.

RE ResourceClassification: all good. I was just curious.

Can confirm we are on the same page RE the sub-property issue. Something that needs to be cleaned up in NRP one day (if NRP wants to do that rather than being replaced by something else...)

The queries you've defined are helpful in inferring schemas, but in a mutation those sub-objects are probably just IDs rather than records, because the referenced things already exist. In the first mutation I threw in as a test, I've also been doing some field munging to maintain compatibility with NRP. It's a bit verbose, so I might stop. But I think the Id suffix is actually rather good, because it helps to differentiate nested objects (which some mutations will have) from references. Though (thinking aloud), if they're suffixed then the translation is going to have to happen somewhere, probably on reading the value out (most semantically sensible IMO- 'read' actions have the effect of inflating IDs to full records), or on performing the save action. In any case we definitely need to discuss things more before making any final decisions for the production version.

Having differing inputs (ID vs. new resource) for affects can be done with union types, but do we need that for GFD? It looks like @sqykly has already done the backend for it, but I'm not sure that the GFD UI needs to be able to do it.

I thought [the GFD scenario file] was more to run the scenario without the React and graphql pieces... but even then, sounds like it points to an intermediate layer above the schemas?

Correct. But I also need to load it up into the GraphQL layer so that I can get access to all the objects it pre-populates. There's no other way to get handles on them at present. Basically we need to be able to run ready multiple times without it breaking since it will be called both in the REPL and the UI. But that's already taken care of, I think. No need to investigate, I've got the translations covered already.

best to consider the VF published definitions over what you see in that graphql api that we worked on.

It looks like there's some additional stuff on there that wasn't there previously, but I still feel a bit like it's lacking the level of explicitness I'm looking for. The relationship names seem to be missing for one, eg. where is the description of agent.ownedEconomicResources? I suspect the UML spec might be a bit outdated for getting the job done... where were those diagrams generated from? The Turtle files in https://github.com/valueflows/agent etc? The other issue is RDF namespace prefixes- I'm not quite sure what to do with those, but wanted to clarify that you'd just strip the prefix for a GraphQL field name? So rdfs:label would just be label?

I basically take this as another hint that we should start some efforts to define a GraphQL schema for ValueFlows, given that the SSB and AP efforts are also working with it. We need some globally shared agreement for the target we're all aiming to hit. What's the best way to get started with that? All I've ever really done in the VF gitter is lurk about...

For @sqykly:

GraphQL's idea of a "mutation" is a mutation to the system as a whole.

Agree that inventory might be a good way of wiring things up, but I may have already done it the proper way. In fact I think @fosterlynn's inventory queries are already serviced by what I have. This should work, no?

The others you've mentioned I think will probably stay out of GraphQL for now. I think we've spoken about this elsewhere and come to consensus on the layers of abstraction at play here- REPL for GFD-specific logic calls, GraphQL for querying with lower-level VF terminology. I don't think we're doing any mutations from the UI, only from the REPL. But I could be wrong- that's up to those driving the demo scenario.

And yes, $token was a JWT used by the Django backend. Those can be ommitted for Holochain.

The reason I like the idea of keeping those functions and algorithms on the server is that it has access to all the computed properties and link repos that make things work

That makes sense. It looks like you're only doing one step though, rather than recursing? So I think we're all on the same page here and my comments in #18 still apply. Basically, we want the logic on the server, but we don't want it to be recursive.

Done to satisfaction for GFD & working end-to-end now

h-REA / holo-rea-proto

Bind GraphQL API to Holochain API #12