# Records

> Every org.tangled.* record type, where it is stored, and its record key rule, plus the legacy sh.tangled.* records still in use.

Tangled data lives in AT Protocol records. Each record is stored either in a **user’s PDS** (things a person owns: profile, stars, follows) or in the **repository DID’s account on its knot** (things about a repository: issues, pull requests, comments). Schemas are in [`lexicons/org/tangled/`](https://tangled.org/tangled.org/core/tree/master/lexicons/org/tangled).

```sh
$ curl "https://knot.example.com/xrpc/com.atproto.repo.listRecords?repo=did:plc:repoxyz&collection=org.tangled.track.ticket&limit=1"
```

Records in a repository account are written through the knot (`com.atproto.repo.createRecord` and friends, or by the knot itself). The knot checks the caller’s permission and stamps the record with `x-tngl-editor`, the DID of the account that made the change.

Location key:

* **User PDS**: the author’s own account.
* **Repo account**: the repository DID’s account, hosted by its knot.

## Repositories

| NSID                             | Stored in        | Record key      | Purpose                                                                                                                                                                                                                                                   |
| -------------------------------- | ---------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org.tangled.repo.manifest`      | Repo account     | `self`          | Repository metadata (description, website, topics, spindle DID, fork or import source) and the `declaration {owner, name}` half of the ownership claim. Written by the knot.                                                                              |
| `org.tangled.repo.declaration`   | User PDS (owner) | Repository slug | The owner’s half of the claim: `{repo: repoDid}`. A repository is listed under `owner/slug` only while manifest and declaration agree.                                                                                                                    |
| `org.tangled.graph.collaborator` | Repo account     | Invitee DID     | Collaboration offer. Indexed by bobbin. The repo owner will create it by sending a request to `com.atproto.repo.createRecord` with this NSID, conversely removing it with `deleteRecord`; the knot grants collaborator access from the record’s presence. |
| `org.tangled.label.definition`   | Repo account     | any             | A label in the repository’s catalogue: `{name, color}`.                                                                                                                                                                                                   |

## Issues and pull requests

| NSID                       | Stored in    | Record key               | Purpose                                                                                                                                                                             |
| -------------------------- | ------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org.tangled.track.ticket` | Repo account | TID (minted by the knot) | An issue, or a pull request when `targetBranch` is set. Holds title, body, state (`open`, `closed`, `completed`) and labels. Only the author or a maintainer can change state.      |
| `org.tangled.review.patch` | Repo account | The record’s own CID     | One immutable revision of a pull request: `{ticket, base, head}` commit IDs, plus an optional `source` naming the repo DID and branch it came from. Each resubmission adds a patch. |

## Discussion and reactions

| NSID                            | Stored in    | Record key               | Purpose                                                                                                                                                    |
| ------------------------------- | ------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org.tangled.feed.comment`      | Repo account | TID (minted by the knot) | A comment on a ticket, patch or string, with optional `replyTo`. Images and video attach through the markdown `blobs`.                                     |
| `org.tangled.feed.reaction`     | Repo account | TID (minted by the knot) | An emoji reaction on a record. Create and delete only.                                                                                                     |
| `org.tangled.graph.attestation` | User PDS     | TID                      | The author’s claim that a knot-written record is really theirs: `{subject, change}` where `change` is the COB change ID, from the write’s `x-tngl-change`. |

## Social graph

| NSID                            | Stored in | Record key  | Purpose                                                                                 |
| ------------------------------- | --------- | ----------- | --------------------------------------------------------------------------------------- |
| `org.tangled.actor.profile`     | User PDS  | `self`      | Profile: avatar, bio, links, location, pronouns, pinned repositories, `isOrganization`. |
| `org.tangled.feed.star`         | User PDS  | TID         | Star on a repository DID or a record.                                                   |
| `org.tangled.feed.subscription` | User PDS  | TID         | Subscription to a repository or a thread; `ignore` mutes it. Drives notifications.      |
| `org.tangled.graph.follow`      | User PDS  | Subject DID | Follow another account.                                                                 |
| `org.tangled.graph.vouch`       | User PDS  | Subject DID | `vouch` or `denounce` another account, with a reason and up to 10 evidence links.       |

## Keys and strings

| NSID                         | Stored in | Record key          | Purpose                                                                                                                                                                                                        |
| ---------------------------- | --------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org.tangled.key.sshKey`     | User PDS  | TID                 | SSH public key with `usages` `auth` and/or `sign`. Written by web key settings and GitHub import. The knot authenticates pushes with keys whose `usages` include `auth` (or omit `usages`); bobbin indexes it. |
| `org.tangled.snippet.string` | User PDS  | any (TID preferred) | A string (gist): description plus one text file blob up to 1 MB.                                                                                                                                               |

## Git

| NSID                   | Stored in    | Record key | Purpose                                                                                                                                                  |
| ---------------------- | ------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org.tangled.git.refs` | Repo account | `self`     | Snapshot of every ref and the default branch, rewritten by the knot after each push. Knotmirror syncs from it. Spindle reads the default branch from it. |

## Shared objects

Embedded in other records, never stored alone: `org.tangled.git.oid`, `org.tangled.embed.commit`, `org.tangled.markup.markdown` (text up to 256 KiB plus blobs), `org.tangled.markup.embed.image`, `org.tangled.markup.embed.video`, `org.tangled.label.defs`, `org.tangled.repo.defs`.

The [API](/docs/api/bobbin/) pages list the methods that read and write these records.