specs/git_ns/drift/resolve/v0_4/payload
library
Classes
-
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.
-
DriftSelector
-
Which of the repository's outstanding drift items to resolve. Drift items carry no
identifier of their own: they are recomputed by the bridge and replaced wholesale
by every git-ns/bridge/event. An item is selected by its
type, and for the three
role types also by the account whose role differs, which is unique among a
repository's outstanding items.
-
ForgeAccount
-
A person's account on one forge.
id is authoritative; login is for display
only, because logins can be renamed and re-registered.
-
Payload
-
An owner of a repository, or a namespace admin over it, resolves one reported drift
item:
adopt records the forge-side role as a VTC right for the member the
resolver names, under the same rules as git-ns/right/grant; revert has the bridge
undo the forge-side change.
-
Response
-
What the resolution did, and where the repository's sync now stands.
-
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.
-
PayloadAction
-
adopt — record the forge-side role as a VTC right, so the projection comes to
match the forge. revert — have the bridge make the forge match the projection
again.
-
ResponseAction
-
The action taken, as requested.
-
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, gitlab.com, or a self-hosted Forgejo or GitLab 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, Forgejo and GitLab 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.
-
RepoResource
= String
-
A forge-qualified resource naming exactly one repository:
<forge-host>/<owner>/<repo-path>, lowercase, where the repository path has 1 to
21 segments (see Resource).
-
Resource
= String
-
A forge-qualified resource, all lowercase:
<forge-host>/<owner> for a namespace,
or <forge-host>/<owner>/<repo-path> for one repository — github.com/acme,
github.com/acme/widgets, codeberg.org/acme. On a forge with nested groups
(GitLab) the repository path holds the subgroups between the top-level owner and
the project: gitlab.com/acme/platform/tools/cli is one repository of the
namespace gitlab.com/acme, and a subgroup such as gitlab.com/acme/platform is
not a resource. A repository path has 1 to 21 segments (GitLab: 20 levels of
subgroup and the project); GitHub and Forgejo repository paths are always one. 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.
