specs/git_ns/shared/v0_5/git_ns library

Classes

AdminRightRow
One right as the administrator's rights console shows it: a recorded RightRecord restated with the membership facts an administrator needs (subjectMember, granterDeparted), or a role-derived grant that carries no record. git-ns/right/list and git-ns/right/issued-by-departed are its only producers.
Bootstrap
Whether each step that turns commit trust on for a repository is in place, as last reported. A step that this forge's plan does not need reads true.
BreakGlass
How a self-granted right came to be, and whether another administrator has since ratified it. A record whose breakGlass has no ratifiedBy is unratified: it is live and published like any other right, it does not count toward the last-owner or last-admin invariants, and any community administrator or namespace admin of its namespace may revoke it. Ratification (git-ns/right/ratify) sets ratifiedBy and ratifiedAt; from then on the record is an ordinary grant, and breakGlass stays as its history. Never published to the Trust Registry.
DriftItem
One difference between the forge's observed state and the VTC's projection of a repository.
ForgeAccount
A person's account on one forge. id is authoritative; login is for display only, because logins can be renamed and re-registered.
GitNamespace
The VTC's binding to one owner on one forge.
RepoSummary
One repository as the VTC records it.
RightRecord
One recorded right. Implied rights (§4.2 of the rights model: own implies maintain implies commit.sign on the same resource; ns.admin implies repo.create and own across its namespace) are not records and never appear as RightRecords. A record carrying breakGlass was given by its subject to themselves through git-ns/right/break-glass; it is a real right, published like any other, and is shown with that flag on every surface that shows the record.
Sync
How the forge compares with the VTC's projection for one repository.

Extension Types

DriftItemType
roleAdded — someone holds a forge role the projection does not give them. roleRemoved — a projected role is missing. roleChanged — a projected role is present at another level. requiredCheckMissing — the verify-trust check is no longer required. protectionWeakened — branch protection or a ruleset is weaker than the projection in another way (force-push allowed, bypass actors added). bootstrapMissing — a bootstrap file or variable is gone.
DriftType
The kinds of drift, named so that a task can select a drift item by kind. The same values, with the same meanings, as DriftItem's type, which keeps its own inline list so that DriftItem stays textually identical to 0.1; the two lists change together. roleAdded — someone holds a forge role the projection does not give them. roleRemoved — a projected role is missing. roleChanged — a projected role is present at another level. requiredCheckMissing — the verify-trust check is no longer required. protectionWeakened — branch protection or a ruleset is weaker than the projection in another way (force-push allowed, bypass actors added). bootstrapMissing — a bootstrap file or variable is gone.
ElevatedRight
The three rights that carry authority over other people's rights: git.ns.admin, git.repo.create (which makes its holder the owner of every repository they create) and git.repo.own. Separation of duties applies to these: nobody grants one to themselves through git-ns/right/grant, or records one for themselves through any other task that grants on the actor's own authority. The explicit self-grant is git-ns/right/break-glass. git.repo.maintain and git.commit.sign are not elevated.
GitNamespaceKind
Whether the owner is an organisation or a personal account, as the forge reports it. Present once known: a bridge-mode namespace learns it when binding completes, and a manual-mode namespace MAY never learn it.
GitNamespaceMode
bridge — a bridge service acts on the forge for this namespace (creates repositories, projects roles, reports drift). manual — no automation; people with forge access carry out the steps the VTC names, and the VTC governs the rights alone.
GitNamespaceState
pending — binding has started and the forge-side proof has not arrived yet. bound — the VTC governs rights under this namespace.
RepoSummaryState
pendingCreate — the name is reserved and the repository is not yet confirmed on the forge. active — managed. archived — archived through git-ns/repo/archive; commit rights on it are revoked. detached — no longer governed: its namespace was unbound, or it moved outside the namespace. orphaned — its last owner left the community and ownership passed to the namespace admins, who have not yet named a new owner. unmanaged — it exists on the forge inside a bound namespace but was never created or adopted through the VTC.
RepoVisibility
Repository visibility on the forge.
One of the five git rights. Each string is also the TRQP action the VTC publishes the right under in its Trust Registry, so it is carried verbatim. git.ns.admin and git.repo.create apply to a namespace resource; git.repo.own and git.repo.maintain to a repository resource; git.commit.sign to either.
RightOrigin
Where a right an administrator sees came from. recorded — a git-ns/* record, governed by the rights model and returned nowhere the subject cannot eventually see it through git-ns/view. roleDerived — a v0.1 \[hooks.git-trust\] grant_on_role grant: published by the hook relay from the community's own role configuration, never written by any git-ns/* task, and not itself a RightRecord — it has no grantedAt, no expiresAt and no reason, only a subject, a right and a resource.
SyncState
inSync — the last comparison found no drift. drift — it found some, listed in drift. pending — a change has been sent to the forge and not yet confirmed. unchecked — nothing compares this repository (a manual-mode namespace).

Typedefs

Did = String
A bare DID in the W3C DID Core syntax (§3.1): did:, a method name of lowercase letters and digits, :, and a method-specific id of colon-separated segments drawn from A-Z a-z 0-9 . - _ and percent-encoded octets, the last segment non-empty. A DID URL is not a DID: no path, query or fragment (/, ?, #), so a verification-method id such as did:key:z6Mk…#z6Mk… is refused. Compared by exact string equality — no case folding or percent-decoding. A consumer MUST still treat the value as data: the pattern keeps shell metacharacters, whitespace and quotes out of the wire form, but it does not make a DID safe to splice into a command or markup.
ForgeHost = String
The lowercased DNS host of a forge: github.com, a GitHub Enterprise Server host, codeberg.org, or a self-hosted Forgejo instance such as git.example.org. No scheme, no port, no path. The host is a segment of every resource, so a right never crosses forges.
ForgeId = String
An identifier the forge itself assigns — a repository id, a user or organisation id — carried as a string so a forge whose ids are not numbers needs no new version. GitHub and Forgejo ids are decimal integers written as strings ("812736451"). Unlike a name, it survives renames and transfers, which is why rights and bindings are keyed by it.
NamespaceId = String
The VTC's opaque identifier for a namespace, assigned when it is bound. Stable for the life of the binding; never reused for another binding.
RepoResource = String
A forge-qualified resource naming exactly one repository: <forge-host>/<owner>/<repo>, lowercase.
Resource = String
A forge-qualified resource: <forge-host>/<owner> for a namespace, or <forge-host>/<owner>/<repo> for one repository, all lowercase — github.com/acme, github.com/acme/widgets, codeberg.org/acme. The forge is never implied: acme/widgets alone is not a resource. Containment is by whole segment: github.com/acme contains github.com/acme/widgets and does not contain github.com/acme-labs/x or codeberg.org/acme/widgets.
Segment = String
One lowercased owner or repository name. Forges compare these case-insensitively, so the wire form is always lowercase and a producer lowercases before sending. A leading . is refused, which rules out . and ...