Crate vgi_forge 

Forge-neutral adapter layer for VGI git namespaces.

A VTC governs who may create, own, maintain and commit to repositories in a namespace; the forge (GitHub, Forgejo, …) is where that is enforced. This crate is the seam between the two: the Forge trait an adapter implements, the ForgeHooks it may add, and the data both sides exchange — Resources, EffectiveRights, Capabilities, bootstrap plans, ForgeEvents and Drift.

Nothing here talks to a forge. Adapters live in their own crates (vgi-forge-github first), so the core compiles without any forge’s HTTP stack, and a forge’s limitations reach the core only as Capabilities — never as a branch on which forge it is.

Three rules hold across every adapter:

• Resources are forge-qualified and normalised by the one grammar in vgi_core::resource, so a grant, a registry tuple and a verify-trust query name a repository with the same bytes.
• Roles round down. A forge with fewer role levels gives less than the community asked for, never more (collapse_to_ladder).
• Accounts are numeric ids. Logins are display-only; a renamed and re-registered login must never inherit a role.

Structs

ApplyReport

Result of converging a repository’s roles.

BindCallback

The forge’s redirect back to the bridge after a bind.

BindRequest

Start binding a namespace (§4.1 step 1).

BootstrapReport

Result of run_plan. In-process only (it carries ForgeError); the bridge reports it to the VTC in its own job-result shape.

BootstrapStep

One step of a bootstrap plan.

Capabilities

What a forge — and one namespace on it — can do (§5.8).

Collaborator

A collaborator as observed on the forge.

EffectiveRights

The rights one subject holds on one resource, closed under implication.

ExtraFile

A community-supplied file to commit during bootstrap.

ForgeAccount

A person’s account on a forge. The numeric id is authoritative; the login is for display and can be renamed and re-registered (§4.4).

ForgeEvent

A verified, translated webhook delivery.

Namespace

A bound namespace, as the adapter needs it (§4.1). The VTC’s record has more (id, boundBy, boundAt); the adapter needs only what locates the owner on the forge and the credential that acts on it.

NamespaceBinding

A completed bind.

NoHooks

Hooks that do nothing.

Projection

What the VTC says a repository should look like on the forge: the enforced projection of §2.

ProtectionSpec

Branch protection to enforce on the default branch.

ProtectionState

The default-branch protection that makes the check mean something, as observed. Each flag is the protective state, so Default is “nothing protected”.

RepoSettings

Repository settings a bootstrap enforces alongside the protection.

RepoSpec

A repository to create (§5.2 git-ns/repo/create).

RepoState

A repository as observed on the forge.

Resource

A normalised forge-qualified resource: github.com/acme or github.com/acme/widgets.

RoleAssignment

One person’s desired role on one repository.

RoleChange

What happened to one person in crate::Forge::apply_roles.

RoleMap

Which forge role each repository tier asks for, before the forge’s ladder is applied (§4.2’s “GitHub projection (org)” column is the default).

VgiConfig

Forge-neutral inputs to a bootstrap plan.

Enums

BindStep

Where to send the admin next.

BootstrapComponent

Which part of the VTC’s bootstrap status (§4.3 bootstrap) a step satisfies — the four dots on the Repos page.

CheckSourceGuard

What keeps a repository’s check out of reach of the pull request it checks (§9), as observed.

Drift

A difference between forge state and the VTC projection (§5.6 table).

ForgeError

A failed forge operation.

ForgeEventKind

What a ForgeEvent reports.

ForgeKind

Which forge software an adapter speaks.

ForgeRole

A person’s role on a repository, on the forge’s side, as a point on the common ladder. Ordered: None < Read < … < Admin.

HookDecision

What a hook wants the core to do.

InstallationChange

How an automation installation changed.

LinkCallback

Completion input for a link. Debug redacts the device code, as for LinkStep.

LinkMethod

How a member links their forge account (§4.4).

LinkStep

Where a member goes to link their account.

MemberChange

How a membership or collaborator changed.

MergeMethod

A way a pull request can land on the default branch.

NamespaceKind

Whether a namespace is an organisation or a personal account (§3, §8).

ProtectionGap

One way the protection falls short of §5.3.

RequiredCheckKind

How a forge makes a status check required (§5.8 table).

Right

One of the five git rights a VTC grants (§4.2), by registry action.

RoleOutcome

Outcome of one role change.

StepAction

What a step does.

StepOutcome

What running one step did.

Unlisted

What to do with direct collaborators the desired set does not mention.

Visibility

Repository visibility.

Constants

DEFAULT_REQUIRED_CHECK

The required status check’s default name: the verify-trust job’s name.

OWNER_REPO_DEPTH

Path depth on forges whose paths are exactly owner[/repo] — GitHub and Forgejo (§4.5).

Traits

Forge

One forge implementation. Stateless apart from its credentials and the namespaces it has been told about; the core owns all desired state and hands the adapter a plan.

ForgeHooks

Optional per-adapter hooks. Every method defaults to HookDecision::Continue; an adapter overrides only what its forge does differently.

Functions

collapse_to_ladder

Fit requested onto a forge’s ladder: the highest level on the ladder that does not exceed it, or ForgeRole::None when every level does.

default_diff

The default crate::Forge::diff: compare observed state with the projection field by field. Roles are matched on the numeric account id, never the login; a pending invitation counts as present.

protection_gaps

Protection shortfalls of observed against a required check.

run_plan

Run steps in order against repo, stopping at the first failure.

validate_repo_path

Validate a repository-relative path for a StepAction::WriteFile: no absolute paths, no empty, . or .. segments, no backslashes. Adapters call this before building a URL from it.

Type Aliases

Result

Shorthand for adapter results.

Attribute Macros

async_trait