# Radicle Inspect #001 Notes
Topic: Collaborative Objects (COBs)

Format:
- Study group -- people ask questions, it's a conversational format
- Feel free to add questions async in Jitsi chat

## Notes
What are COBs?
- Core collaboration primitive in Radicle
- Extensible system. Users and devs can create different objects that have their own rules.
- A way to implement custom logic in a radicle repo that gets replicated and runs on everyones machine

Starting point:
- Where they are represented and how they are stored
- You have your radicle / git repo
- In a git repo you have
- /refs
- /heads
- /tags
- /cobs - we create an extra namespace for cobs. each cob has its own typename. they are in reverse domain notation e.g.:
- xyz.radicle.issue/
- Issues will live under this
- xyz.radicle.patch/
- Patches live under this
- these are not in working copy
- these are in stored copy in your radicle home
- Fintan: I might just clarify that this in the Radicle storage and not the working copy -- so these refs are under each NID namespace 😃
- when you are operating, operating directly on these cobs

Example

Alice
- repo1
- cobs

Bob
- repo1
- cobs

These cobs are synced

/xyz.radicle.issue/ hierarchy
- You have a git ref under each issue (e.g. the issue id)

In git you have a few different object types - e.g. refs. which are names that point to commits / objects

commits - everyone here knows

blobs - are essentially files

trees - paths to blobs

trees point to blobs
refs point to commits
commits point to trees

Yorgos wanted to look at example:

creating an issue

- There is a root commit
- Then within it, there is a comment e.g. "Hello world"

Someone replies: "Hi there"

There will be a relationship between commits

Root commit will be a parent to the reply

If someone replies "whats up", this then points to "Hi there", which points to "hello world"

Commit
---
id (sha1) --> this is the issue id
tree

points to tree object, then the tree points to a blob

this blob contains the payload, which is a json object

{
"type": "comment"
"body": "hellow world"
reply-to: "<sha1>"
}

There is a commit for all actions, like changing the status etc. They all have same datastructure, just the "blob" has a different type.

Question: how is a reply to a comment mapped?

there is reply to in the blob
each comment has unique id, can reply to the root, or directly to an existing comment id

head pointer would point to "root" of issue

If you add a comment, like "c1", c1 will point to root, and "head" will point to "c2"

If you add another comment, "c2", then the same thing happens, e.g. c2 points to c1, and head points to c2.

lets add another user fintan, make the first one cloudhead

fintan adds a new comment, it points to c2

cloudhead doesnt have f1 on his device yet, and he adds c3 and it points to c2

as far as the cob is concerned, they are concurrent and happened at the same time

eventually, the state has to be synchronized

lets say there was a synchronization event

cloudhead wants to add a new comment: c4

there are two theads right now.

his c4 commit will have two parents (f1, c3)

this is a regular git commit that happens to have more than one parent

this is the reality of p2p, offline first, concurrent system design

end up with nonlinear history - a DAG

directed, bc the arrows always point in one direction

Question: merge function

Lorenz
I'm waiting till we go lower level and have a question about the `cob::Evaluate` interface.

Topological sort that looks at all the nodes of a graph and sorts them by the edges

If you do a topological sort, doing an ordering

There are certain orderings that are known

if f1. id > c3.id

Lorenz: The order itself doesn't matter too much, it just needs to be consistent among all participants.

Fintan: You could say that you're turning a partial order into a total order by picking a way to break ties

how to access the cobs for app development?

list

ops = [ r , c1, c2 .... ]

eval ( [ops]) --> issue

eval function is implemented for each cob type

let ops = topo sort (graph)
let issue = eval (ops)

then clin (issue) --> print

theres this interface, cob.evaluate reply
-- it takes an iterarator of concurrent operations

if you unpack eval ([op])

---> apply (issue)

Terminal example:

inside home/.radicle/storage

- it is what is in there that is being replicated to network

git show-ref inside a repo
will be shown all the refs

why is hash on left different from hash on right?
hash on right is the issue id which is the root commit id, whereas hash on the left is the head / last comment

the way we store COBs inside git commits is not how we store code

Vitalii (glukki)
Vitalii (glukki) says:so you can calculate state out of available actions! neat!
16:59
avatar
Lorenz Leutgeb
Lorenz Leutgeb says:Operation vs. Action? Don't the blobs 0 and 1 contain actions?
17:00
yorgos
yorgos says:Great session!! Afraid I need to drop, but this was time well spent, I think! 👌
yorgos says:thanks !!
17:10
D
Derick
Derick says:I have a question that I'll ask here in chat:
Derick says:To have a custom COB type, is it necessary to run a custom build of Heartwood that was built with the code for the custom COB? I.e. is it that such a custom build must be distributed to everyone who wants to use the custom COB? Or can the implementation of the custom COB be provided as some kind of plug-in (so that an official distribution of the radicle binaries that everyone already has can be used by them)?

-- it is the latter, but we dont help you that much to do that right now
-- radicle will replicate whatever cobs you put in the repo. it doesnt need the evaluation function. it just needs the data. it looks at the commits. thats under cobs hierarchy, ill replicate it
- for users to interpret the cob, they will need a custom evaluation fucntion. That can be supplied as a separate tool, a desktop app, etc.
- rad just like git, it will look for that in your path, like rad-(thing).
- can distribute rad-lol to ppl, then they can all rad lol

17:11
M
maninak
maninak says:I didn't know those details about the design, especially the root commit's refs to id doc etc, that's damn well designed, kudos! 👍

Jan
two questions:
- how could the state of the issue be created in the working copy if the root hash of the issue cob was not available in the demo wiht the rad cli command?
- do you store a snapshop of the reduced final cob states somewhere or is it always fast enough to recreate everything as needed?

17:12
LW
Lars Wirzenius
Lars Wirzenius says:we could have a "hello world" COB implementation to make it easier to learn how to implement new COB types
17:15
M
maninak
maninak says:@lars +1
17:16
avatar
Sebastian Martinez
Sebastian Martinez says:👆👆
17:16
LW
Lars Wirzenius
Lars Wirzenius says:COBs are stringly typed
17:21
L
Lorenz
Lorenz says:Hello world COB using external script will be a test contributed along with rad cob create
Lorenz says:See
https://app.radicle.xyz/nodes/seed.radicle.garden/rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5/patches/6833bcc7c9278a489e7eda02a7e5fc82caef6f62?tab=changes#radicle-cli/examples/rad-cob-create.md:H0L0

17:21
avatar
Sebastian Martinez
Sebastian Martinez says:@lorenz 🙏
17:21
M
maninak
maninak says:@lorenz ❤️
maninak says:I believe --repo is a flag for `rad patch` commands
17:23
avatar
Sebastian Martinez
Sebastian Martinez says:rad patch --repo <rid> works
Sebastian Martinez says:also for issue

cache command would have to be implemented per cob

to dos:
explain what one has to implement on their own for COBs

This is me recording!
16:02
me says:
https://hackmd.io/meJDgnSVTrG-igCTEbJD7w

16:03
Fintan Halpenny
Fintan Halpenny says:😮
Fintan Halpenny says:👏
Fintan Halpenny says:I might just clarify that this in the Radicle storage and not the working copy -- so these refs are under each NID namespace 😃
16:09
R
rudolfs
rudolfs says:👏
16:14
D
Derick
Derick says:👏
16:14
avatar
Sebastian Martinez
Sebastian Martinez says:👏
16:15
Lorenz Leutgeb
Lorenz Leutgeb says:👏
16:14
Daniel Kalman
Daniel Kalman says:👏
16:15
yorgos
yorgos says:I think looking into an example would help
16:15
Lorenz Leutgeb
Lorenz Leutgeb says:I'm waiting till we go lower level and have a question about the `cob::Evaluate` interface.
16:15
LW
Lars Wirzenius
Lars Wirzenius says:(remarkable docs say there is no limit to page length)
16:18
Fintan Halpenny
Fintan Halpenny says:👍
16:19
M
Mihalis
Mihalis says:How is a reply to a comment mapped?
Mihalis says:👍
16:24
avatar
Sebastian Martinez
Sebastian Martinez says:remarkable changes swiggly lines that are close to straight lines into straight lines.
16:36
Fintan Halpenny
Fintan Halpenny says:rude
16:37
LW
Lars Wirzenius
Lars Wirzenius says:squiggly to strraight only if you keep the pen pressed at the end of the line without moving it
16:38
Lorenz Leutgeb
Lorenz Leutgeb says:The order itself doesn't matter too much, it just needs to be consistent among all participants.
16:39
Fintan Halpenny
Fintan Halpenny says:You could say that you're turning a partial order into a total order by picking a way to break ties
16:41
Lorenz Leutgeb
Lorenz Leutgeb says:I'd like to ask something before demo.
Lorenz Leutgeb says:
https://app.radicle.xyz/nodes/seed.radicle.garden/rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5/tree/radicle-cob/src/object/collaboration.rs#L76

Lorenz Leutgeb says:I see, thanks.
16:48
M
Mihalis
Mihalis says:👍
16:50
avatar
Sebastian Martinez
Sebastian Martinez says:👏
16:50
me says:the left changes and right doesnt change?
16:55
avatar
Sebastian Martinez
Sebastian Martinez says:exactly
16:55
Vitalii (glukki)
Vitalii (glukki) says:so you can calculate state out of available actions! neat!
16:59
Lorenz Leutgeb
Lorenz Leutgeb says:Operation vs. Action? Don't the blobs 0 and 1 contain actions?
17:00
yorgos
yorgos says:Great session!! Afraid I need to drop, but this was time well spent, I think! 👌
yorgos says:thanks !!
17:10
D
Derick
Derick says:I have a question that I'll ask here in chat:
Derick says:To have a custom COB type, is it necessary to run a custom build of Heartwood that was built with the code for the custom COB? I.e. is it that such a custom build must be distributed to everyone who wants to use the custom COB? Or can the implementation of the custom COB be provided as some kind of plug-in (so that an official distribution of the radicle binaries that everyone already has can be used by them)?
17:11
M
maninak
maninak says:I didn't know those details about the design, especially the root commit's refs to id doc etc, that's damn well designed, kudos! 👍
17:11
J
jan
jan says:two questions:
- how could the state of the issue be created in the working copy if the root hash of the issue cob was not available in the demo wiht the rad cli command?
- do you store a snapshop of the reduced final cob states somewhere or is it always fast enough to recreate everything as needed?
17:12
LW
Lars Wirzenius
Lars Wirzenius says:we could have a "hello world" COB implementation to make it easier to learn how to implement new COB types
17:15
M
maninak
maninak says:@lars +1
17:16
avatar
Sebastian Martinez
Sebastian Martinez says:👆👆
17:16
LW
Lars Wirzenius
Lars Wirzenius says:COBs are stringly typed
17:21
L
Lorenz
Lorenz says:Hello world COB using external script will be a test contributed along with rad cob create
Lorenz says:See
https://app.radicle.xyz/nodes/seed.radicle.garden/rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5/patches/6833bcc7c9278a489e7eda02a7e5fc82caef6f62?tab=changes#radicle-cli/examples/rad-cob-create.md:H0L0

17:21
avatar
Sebastian Martinez
Sebastian Martinez says:@lorenz 🙏
17:21
M
maninak
maninak says:@lorenz ❤️
maninak says:I believe --repo is a flag for `rad patch` commands
17:23
avatar
Sebastian Martinez
Sebastian Martinez says:rad patch --repo <rid> works
Sebastian Martinez says:also for issue
17:24
LW
Lars Wirzenius
Lars Wirzenius says:TCL - Todayl Cloudhead Leanred 😃
17:30
L
Lorenz
Lorenz says:Correct. show uses cache, log does not.
17:33
M
maninak
maninak says:Gotcha, makes sense. Thank you, both.
17:33
LW
Lars Wirzenius
Lars Wirzenius says:I don't think I've used it either. Fintan had to leave.
Lars Wirzenius says:i = rad issue ache
17:34
M
maninak
maninak says:`rad cach` is a great tip as a fallback, thank you!
17:34
Q
qxotk
qxotk says:Might be good to have a verbose mode showing if cache used.
qxotk says:Got it.
17:36
J
jan
jan says:thanks that was super interesting!
17:36
R
rudolfs
rudolfs says:👏
17:37
avatar
Sebastian Martinez
Sebastian Martinez says:was great tyvm :applaud:
17:37
L
Lorenz
Lorenz says:Good sesh.
17:37
R
rudolfs
rudolfs says:was real good!
17:37
D
Derick
Derick says:I'd already figured out most of what you covered in the first hour. But it was really good to have you confirm it.
17:37
M
maninak
maninak says:That was very well delivered, the remarkable part was dope, all super insightful and not boring at any point throughout.
17:37
M
Mihalis
Mihalis says:Pretty good and informative! Thanks!