specs/git_ns/shared/v0_2/git_ns library

Classes

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.
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.
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.
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.
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 DID, compared by exact string equality.
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 ...