Files
buzz/docs/nips/NIP-RB.md
2026-09-15 11:56:20 +02:00

5.2 KiB

NIP-RB

Repositories and Branches

draft optional relay

Depends on: NIP-CS (conversation subjects), NIP-34 (Git announcements).

Kinds

Kind Name Location Claim
45011 Repository channel exclusive
45014 Branch thread attachment

These are regular stored events. NIP-CS defines identity, revision chaining, controller authority, and common tags. A repository subject maps a Buzz identity to a NIP-34 repository; it does not create another Git repository. A branch subject identifies a collaboration lifecycle, not a ref-state snapshot.

Repository event

{
  "kind": 45011,
  "tags": [
    ["cs", "1"],
    ["d", "<repository-uuid>"],
    ["h", "<repository-channel-uuid>"],
    ["location", "channel"],
    ["claim", "exclusive"],
    ["a", "30617:<owner-public-key>:checkout"]
  ],
  "content": "{\"title\":\"Checkout\",\"archived\":false}"
}

Standard signed-event fields are omitted. Updates include prev.

Additional tag Cardinality Meaning
a 1 NIP-34 repository coordinate; exactly two tag elements

The coordinate MUST start with 30617: followed by a 64-character lowercase hex public key, a colon, and the repository identifier. Split on the first two colons only; the remaining identifier is literal. The relay MUST resolve the coordinate to an existing repository announcement in the same community. The coordinate is immutable and unique among repository subjects in that community, including archived subjects.

Content field JSON type Constraints
title string Required; non-whitespace; at most 512 UTF-8 bytes
archived boolean Required

Duplicate and unknown fields MUST be rejected. Archiving prevents new branch subjects but does not delete code, hide discussions, or release the home claim. Clone URLs, commit tips, and ref snapshots remain NIP-34 state, not independently writable fields on this subject.

Branch event

{
  "kind": 45014,
  "tags": [
    ["cs", "1"],
    ["d", "<branch-uuid>"],
    ["h", "<discussion-channel-uuid>"],
    ["location", "thread"],
    ["root", "<discussion-anchor-event-id>"],
    ["claim", "attachment"],
    ["repository", "<repository-uuid>"],
    ["ref", "refs/heads/fix-timeout"]
  ],
  "content": "{\"retired\":false}"
}
Additional tag Cardinality Meaning
repository 1 Buzz repository UUID using NIP-CS encoding
ref 1 Full Git branch ref

Tags have exactly two elements. Both values are immutable. The repository MUST resolve to kind 45011 in the same community and MUST NOT be archived on branch creation. The branch resolves its NIP-34 target through that repository; it MUST NOT repeat an independently authoritative coordinate.

ref MUST start with refs/heads/ and satisfy Git ref-name rules: no empty or dot-prefixed path component, .lock component suffix, trailing dot, .., @{, ASCII control/space, DEL, or any of ~ ^ : ? * [ \\. A branch subject may precede the first push; ref existence is not required. At most one non-retired subject may occupy (community, repository, ref).

Content contains exactly the required boolean retired. Retirement is terminal: a retired branch cannot become active again. A new incarnation uses a new UUID and may claim the released ref slot, but the retired subject retains its conversation association. Ref deletion alone does not retire a subject; rename is retirement followed by creation, not a silent identity rewrite.

Authorization and disclosure

Repository creation requires control of the NIP-34 announcement and channel administration. Its Git access binding MUST match the subject's channel; a conflicting binding MUST be rejected rather than silently overwritten. Later Git metadata writes MUST NOT contradict an adopted binding.

Branch creation and updates require the NIP-CS controller rules, destination channel write permission, and repository administration authority. This is stronger than code read or ordinary push permission: placing a ref name in another channel constitutes disclosure to that audience.

A branch's discussion channel MAY differ from its repository channel. Repository readers do not thereby gain access to the discussion, and discussion readers do not gain code access. Rendering a branch MUST NOT implicitly fetch or expose Git content without a separate repository access check. Git-originated notifications and agent output are subject to the same disclosure boundary.

Queries and compatibility

Query repositories by kind 45011 and h; query branches by kind 45014 and repository, optionally ref. Query discussion attachments by h and root. Relationship filtering MUST precede pagination and use NIP-CS authorization and revision-history semantics.

NIP-34 announcement 30617 and ref state 30618 retain their identities. A 30618 event may describe many refs and MUST NOT serve as a branch subject identity. Pull requests, patches, and their statuses remain separate Git protocol objects. Adopting a repository does not retrospectively restrict copies of previously published metadata or reinterpret legacy comments as private channel replies.