Create ADR for Atomic/Composite graph operations

[neotyk]

Context

Our current Semantic Events where a port of events.cljs, which contained UI informed events, not necessarily graph operations oriented. We have events that are hard to express in current model, like :block/save that results in :page/create as well.

It's time to look at Graph Operations not from UI standpoint, but from point of identifying atomic operations and ways to create composite operations.

Problem

:block/save as many other events are really composition of Atomic Graph Operations, others already are atomic. Implementing :paste without Atomic Graph Operations seems impossible.

Desired outcome

An ADR describing Atomic Graph Operations.

[neotyk]

• How to represent ((⎄ Composite Graph Ops))?
  • Ideas
    • 1. Change Event Protocol to accept list of events
         • This will forget about events like :paste because it will just transfer resulting ((⚛️ Atomic Graph Ops))
         • Event type Composite Event, that contains list of Atomic Graph Ops
         • Even though it might not preserve initiating event. There is plenty of places where we'll just have few Atomic Graph Ops
    • 2 .Extend common event type by adding consequence events
      • Consequence Event is 2 things
        • Main Event (like :block/save or :paste)
        • Consequence Events List
          • Containing however many events to include into transaction resolution
      • This will allow for easier Temporality
        • We'll be able to represent Main Action that moved Knowledge Graph forward
      • It will maintain information about :paste events that injected sub-tree with ((⚛️ Atomic Graph Ops))
    • 3. Use ((1. Change Event Protocol to accept list of events)) & ((2 .Extend common event type by adding consequence events))
         • We need both:
         • ((Event type Composite Event, that contains list of Atomic Graph Ops))
         • ((Consequence Event is 2 things))

[filipesilva]

I'm partial to option B. It sounds a lot like just having a "signal" event for intent.

I even wonder if that's necessary at all, if the intent itself isn't an atomic operation maybe we should instead add extra information onto the atomic operations themselves. Something like {:type :block-edit ... :composite/id "123abc" :composite/order 4 :composite/end 15}. That'd let us know there were several operations part of the same thing.

It does beg the question though: why even include the extra information on the protocol? Maybe we don't need it at all, and the output is just a stream of atomic operations anyway.

The way we think about undo as reverting a single operation makes it sound like it needs the extra batch information though. But that can also be encoded and stored only on the client, or we might have other ways of implementing undo.

I think the real question is "what are the use cases for storing composite graph op information?".

I don't like option A much because it means the API must support potentially large lists of events in a single payload, which can be hard to do depending on the properties of the transport structure. For instance, if we wanted to store events in a Kafka queue, we could easily run into problems if some events can be up to several megabytes. To me this also leaves out option C because it uses option A.