A natural fit for Radicle Collaborative Objects

Hi there @lox 👋🏼

I had a closer look at this repo this week, and found it's very very relevant to [Collaborative Objects (COBs)](https://radicle.dev/guides/protocol#collaborative-objects) in Radicle. In a nutshell, COBs are:
- stored within the git repo, so they're portable,
- signed by the Radicle identity that creates/modifies them (an ed25519 key pair), so fully auditable,
- replicated across peers in the radicle peer-to-peer network, so when I make e.g. an attestation on my machine, it transparently shows up on yours.

With that in mind, and how trivial it is to create custom COBs I then had an agent whip up a quick CLI for working with the `git-attest` COB types from this repo, which I've published [here](https://radicle.network/nodes/index.radicle.garden/rad%3Az3d3JXM3dBskW6yF8ChS7uoCKaMJB).

Note: This is only meant to be a proof-of-concept for how ideas like the one in git-attest could natively be ported to Radicle. For CI runs, there is already [radicle-job](https://radicle.network/nodes/radicle.liw.fi/rad%3Az2UcCU1LgMshWvXj6hXSDDrwB8q8M/) (the COB we use to store CI runs), and there is already a mechanism for approving/requesting changes to Radicle Patches (another COB type - the PR equivalent).

So, with that out of the way:
With `rad-attest` built/installed/added to your path you can use `rad attest` inside radicle repo working copies (`rad` is extensible similar to how `git` is [extensible](https://git-scm.com/docs/git.html#Documentation/git.txt-PATH)).

## Record a code-review attestation

Alice reviews a commit and approves it.

```shell
❯ rad attest review HEAD --result approved --reviewer alice@buildkite.com
c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff
❯ rad attest show HEAD
{
"subject": {
"commit": "b3e5c6a1d4720bb4b42a1029ee22035c4aa19368",
"tree": "702918106d6babba358a3a51dde1f314bb04d9c3"
},
"attestations": [
{
"id": "c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff",
"type": "review",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3", # <--- the radicle identity that signed the attestation
"timestamp": 1781769140000,
"revoked": false,
"supersededBy": null,
"payload": {
"reviewer": {
"issuer": "radicle",
"kind": "human",
"principal": "alice@buildkite.com"
},
"result": "approved"
}
}
]
}
# use the built-in `rad cob` commands to see under the hood
❯ rad cob list --repo $(rad .) --type com.buildkite.attestation
c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff
❯ rad cob show --repo $(rad .) --type com.buildkite.attestation --object c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff
{"subject":{"commit":"b3e5c6a1d4720bb4b42a1029ee22035c4aa19368","tree":"702918106d6babba358a3a51dde1f314bb04d9c3"},"attestations":[{"id":"c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff","type":"review","author":"z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3","timestamp":1781769140000,"revoked":false,"supersededBy":null,"payload":{"result":"approved","reviewer":{"issuer":"radicle","kind":"human","principal":"alice@buildkite.com"}}}]}
```

Attestations are per commit, so `rad attest` just created a new COB (of type `com.buildkite.attestation`) that, for now, just includes the review.

## Attach a CI result

Buildkite runs the unit suite and it passed. We can add this to the list of attestations about that same commit.

```shell
❯ rad attest ci-run HEAD --name unit --result passed \
--runner "https://buildkite.com/some-org/some-project/builds/42" --issuer hosted-ci
c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff
❯ rad attest show HEAD
{
"subject": {
"commit": "b3e5c6a1d4720bb4b42a1029ee22035c4aa19368",
"tree": "702918106d6babba358a3a51dde1f314bb04d9c3"
},
"attestations": [
{
"id": "c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff",
"type": "review",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769140000,
"revoked": false,
"supersededBy": null,
"payload": {
"result": "approved",
"reviewer": {
"issuer": "radicle",
"kind": "human",
"principal": "alice@buildkite.com"
}
}
},
{
"id": "e524f9773bc5435055fd60094fd0782d68168f3a",
"type": "ci-run",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769322000,
"revoked": false,
"supersededBy": null,
"payload": {
"runner": {
"issuer": "hosted-ci",
"kind": "service",
"principal": "https://buildkite.com/some-org/some-project/builds/42"
},
"name": "unit",
"result": "passed"
}
}
]
}

```

## Supersede a previous attestation

Then, Alice notices something she didn't like and decides to change her mind:

```shell
❯ rad attest supersede HEAD c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff \
--result changes_requested --reviewer alice@buildkite.com
c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff
❯ rad attest show HEAD
{
"subject": {
"commit": "b3e5c6a1d4720bb4b42a1029ee22035c4aa19368",
"tree": "702918106d6babba358a3a51dde1f314bb04d9c3"
},
"attestations": [
{
"id": "c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff",
"type": "review",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769140000,
"revoked": false,
"supersededBy": "918cef3de8b6115d1ff4af5d66b5ad4f54767474",
"payload": {
"result": "approved",
"reviewer": {
"issuer": "radicle",
"kind": "human",
"principal": "alice@buildkite.com"
}
}
},
{
"id": "e524f9773bc5435055fd60094fd0782d68168f3a",
"type": "ci-run",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769322000,
"revoked": false,
"supersededBy": null,
"payload": {
"name": "unit",
"runner": {
"issuer": "hosted-ci",
"kind": "service",
"principal": "https://buildkite.com/some-org/some-project/builds/42"
},
"result": "passed"
}
},
{
"id": "918cef3de8b6115d1ff4af5d66b5ad4f54767474",
"type": "review",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769403000,
"revoked": false,
"supersededBy": null,
"payload": {
"reviewer": {
"issuer": "radicle",
"kind": "human",
"principal": "alice@buildkite.com"
},
"result": "changes_requested"
}
}
]
}
❯ rad cob list --repo $(rad .) --type com.buildkite.attestation
c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff
❯ rad cob show --repo $(rad .) --type com.buildkite.attestation --object c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff | jq
{
"subject": {
"commit": "b3e5c6a1d4720bb4b42a1029ee22035c4aa19368",
"tree": "702918106d6babba358a3a51dde1f314bb04d9c3"
},
"attestations": [
{
"id": "c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff",
"type": "review",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769140000,
"revoked": false,
"supersededBy": "918cef3de8b6115d1ff4af5d66b5ad4f54767474",
"payload": {
"reviewer": {
"issuer": "radicle",
"kind": "human",
"principal": "alice@buildkite.com"
},
"result": "approved"
}
},
{
"id": "e524f9773bc5435055fd60094fd0782d68168f3a",
"type": "ci-run",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769322000,
"revoked": false,
"supersededBy": null,
"payload": {
"runner": {
"issuer": "hosted-ci",
"kind": "service",
"principal": "https://buildkite.com/some-org/some-project/builds/42"
},
"name": "unit",
"result": "passed"
}
},
{
"id": "918cef3de8b6115d1ff4af5d66b5ad4f54767474",
"type": "review",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769403000,
"revoked": false,
"supersededBy": null,
"payload": {
"result": "changes_requested",
"reviewer": {
"issuer": "radicle",
"kind": "human",
"principal": "alice@buildkite.com"
}
}
}
]
}
```

## Revoking a previous attestation

Finally, we want to revoke a previous attestation

```
❯ rad attest revoke HEAD e524f9773bc5435055fd60094fd0782d68168f3a \
--reason "pipeline had a bug. Tests failed, but the pipeline reported success."
c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff
❯ rad cob show --repo $(rad .) --type com.buildkite.attestation --object c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff | jq
{
"subject": {
"commit": "b3e5c6a1d4720bb4b42a1029ee22035c4aa19368",
"tree": "702918106d6babba358a3a51dde1f314bb04d9c3"
},
"attestations": [
{
"id": "c7df1185004f9dac07aad2b1c6eadb5d2e1fd7ff",
"type": "review",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769140000,
"revoked": false,
"supersededBy": "918cef3de8b6115d1ff4af5d66b5ad4f54767474",
"payload": {
"reviewer": {
"issuer": "radicle",
"kind": "human",
"principal": "alice@buildkite.com"
},
"result": "approved"
}
},
{
"id": "e524f9773bc5435055fd60094fd0782d68168f3a",
"type": "ci-run",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769322000,
"revoked": true,
"supersededBy": null,
"payload": {
"name": "unit",
"result": "passed",
"runner": {
"issuer": "hosted-ci",
"kind": "service",
"principal": "https://buildkite.com/some-org/some-project/builds/42"
}
}
},
{
"id": "918cef3de8b6115d1ff4af5d66b5ad4f54767474",
"type": "review",
"author": "z6MkrnXJWPndzPBxpBUaE3L3BnMeWpaQdT1V1FvkoCPFSFS3",
"timestamp": 1781769403000,
"revoked": false,
"supersededBy": null,
"payload": {
"result": "changes_requested",
"reviewer": {
"issuer": "radicle",
"kind": "human",
"principal": "alice@buildkite.com"
}
}
}
]
}
```

I hope this helps demonstrate how extensible Radicle is with custom COBs. They can basically be used to capture any primitive and tie that to code, in a secure, verifiable way - with replication already built in.

For any questions on the above, I'd be happy to help!

Start by reading the repository's existing attestation model and command-line entry points, then run the documented review, CI, supersede, and revoke examples to compare them with the proposed Radicle COB workflow. Done should mean that the project has an agreed implementation scope for Radicle support, including how these operations map to the existing attestation format.

Written by the indexing model from the issue text.