specs/git_ns/view/v0_4/payload
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.
-
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.
-
LinkedAccount
-
A forge account linked to the caller's DID with git-ns/account/link, and when the
link completed.
-
Payload
-
A member reads the namespaces, repositories and rights they are entitled to see,
optionally narrowed to one resource, together with the forge accounts linked to
their own DID.
-
RepoSummary
-
One repository as the VTC records it.
-
Response
-
What the caller may see, and the caller's own linked forge accounts.
-
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.
-
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.
-
Right
-
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 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.
-
Ext
= Map<String, dynamic>
-
Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a
reverse-DNS namespace; structure under each namespace is opaque to the framework.
-
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 ...
