Crate onevcs 

Version control and its remote host behind one host-neutral vocabulary.

The review unit is a ChangeRequest — GitHub maps it to a pull request, and a later host maps it to whatever it calls the same thing. Vcs owns the repository side (identities, sessions, preserved work) and RemoteHost owns the host side (opening a change, reading its checks, merging it). A rules file decides, per repository, how a change is published and whether it needs an approval. Everything a process does along the way is emitted as an Envelope.

The shape of one change

session open  →  a --shared clone and one worktree, occupancy-leased: a warm
                  pool slot where the host keeps one, else cut for this run
   →  work happens in the worktree
   →  publish   →  fetch and merge the current base  (bounded resolve-and-requeue)
                →  the repository's own merge path verifies it: its pre-push
                   hook, or the host's required checks on the change request
                →  local-direct squash, or a change request the host lands
   →  session close  →  the branch is copied out and stays; a slot is returned
                        warm, a per-run worktree goes

Everything durable lives under one state root (ONEVCS_HOME, otherwise ~/.onevcs): the registry document, the advisory locks and merge-queue state, the per-session workspaces, the event streams, and their artifacts.

Two surfaces over one decision

run is the command line: it answers a process, with an exit code and a line of prose. A caller embedding this crate wants the decision itself, so the same operations answer values — publish hands back a Publication, close_session the session it released, session what the repository side recorded, preserve what putting a branch on its origin did, recoverable the branches that still hold unpublished work, and EventStream the envelopes one session wrote. The command line is a rendering of those rather than a second path through them.

Re-exports

pub use declaration::Declaration;

pub use declaration::DeclaredTarget;

pub use declaration::InstructionTemplate;

pub use declaration::RegistryId;

pub use declaration::RetiredArtifact;

pub use registry::Identity;

pub use releases::Acknowledgement;

pub use releases::Adoption;

pub use releases::Baseline;

pub use releases::BaselineRecord;

pub use releases::DeclarationPolicy;

pub use releases::DeclarationSource;

pub use releases::Discovery;

pub use releases::Probe;

pub use releases::ReleaseAnswer;

pub use releases::ReleaseDefault;

pub use releases::ReleaseMethod;

pub use releases::ReleaseRule;

pub use releases::ReleaseSource;

pub use releases::ReleaseStatus;

pub use releases::ReleaseStyle;

pub use releases::ReleaseTarget;

pub use releases::ReleasesFile;

pub use releases::RepositoryReleases;

pub use releases::SupersededRelease;

pub use releases::TargetName;

pub use releases::TargetRelease;

pub use releases::TargetSource;

pub use rules::MergePolicy;

pub use workspaces::first_matching;

pub use workspaces::Bound;

pub use workspaces::Span;

Modules

cli

The command-line argument surface.

declaration

The producer’s own release declaration: what one repository publishes.

provenance

What a branch records about how its work came to be there.

registry

The registry document: which repository identities exist, which checkouts belong to each, and where the rules file lives.

releases

The release-targets file: what each repository releases, and how a release of it is learned about.

rules

The rules file: how each repository publishes a change.

workspaces

The workspaces file: how many warm worktree slots each repository keeps on this host, and how many sessions it admits past them.

Structs

ArtifactId

The id of a stored artifact.

ArtifactRef

Evidence too large for a payload: stored by the producing library and referenced by id, to be read back through that library.

ChangeChecks

What a host reports about a change request’s checks, and where it looked.

ChangeDescription

What a caller writes to a change request’s description.

ChangeId

A host’s identifier for a change request.

ChangeRequest

An open change request on the host.

ChangeSpec

What to open a change request for.

Check

One check the host reports on a change request.

Description

A change request’s description as the host holds it.

EventStream

A reader over one session’s event stream, as values rather than as text.

Git

The git implementation of Vcs.

GitHub

The GitHub implementation of RemoteHost, driven through gh.

HeldBy

The live session that still holds a preserved branch.

IdentityMaintenance

One identity, and what maintaining it came to.

Labels

The reserved label keys, plus whatever else a producer stamped.

LineChange

The lines a branch would land, as git counts them against the commit it forked from.

MaintainReport

What pool maintain did: every identity in scope, and what became of each.

NetNegative

A LineChange that removes more than it adds, and the only thing that can be one.

OnOrigin

Where a branch was last put on its identity’s origin without being published.

PoolStatus

What pool status reports: the capacity, and every slot.

PreserveRequest

What to preserve, and where to look for it.

Preserved

What preserving one branch did.

PreservedBranch

A branch that holds work outside its session.

Providers

The repository side and the remote-host side of one run.

PruneReport

What pool prune did: which slots it removed, and which it kept and why.

Publication

What one publication did.

PublishRequest

What one publication was asked for beyond the session it publishes.

Recoverable

Preserved work, whether it reached its base, and what would land it.

RequiredChecks

What a host requires before a merge into a branch, and how much of the host that answer covers.

Selection

Which of the preserved work in scope a report is asked to answer with.

Session

An open session: a per-run shared clone plus a worktree, held under an occupancy lease.

SessionChange

A session’s change request, as the host holds it right now.

SessionHolder

One session that holds a repository’s workspace, as an enumeration reports it.

SessionRecord

Everything the implementation that opened a session records about it.

SessionRequest

What to open a session over.

SessionToken

The handle a session is adopted, published, and closed by.

Sha

A commit hash.

SlotMaintenance

One slot, and what became of it.

SlotStatus

One slot, as pool status reports it.

Subject

A title that can be the subject of the commit a publication lands.

Url

A parsed absolute URL, re-exported so a caller needs no direct dependency on the parser this crate validates change-request URLs with. A parsed URL record.

WorkspaceCapacity

How many sessions one identity can admit right now, and whether one request would be placed.

Enums

CheckSource

One place a host’s answer about a change request’s checks was read from.

DraftReason

Why a change request is a draft, in the shape a machine reads it.

Error

Everything an onevcs operation can fail with.

EventKind

What an event says happened.

FailureKind

Which failure ended a publication, and therefore which exit code says so.

Holding

How a host can tell that a session still holds its branch.

IdentityOutcome

What became of one identity.

Landed

Whether the work reached the base, and — where it did — what says so.

LandingEvidence

Which tier decided a landing, and the commit that is its evidence.

Lifecycle

Where a session is in its life.

Liveness

Whether a session’s owner is still running, which is what makes its lease real.

MaintenanceOutcome

How a maintenance run ended.

MergeOutcome

What merging a change request did.

Phase

Which part of a change’s life an event belongs to.

Preservation

What preserving one branch found to do.

ProtectionSource

One of the ways a host protects a branch, each of which may name required checks.

Provenance

Why a branch was preserved, and therefore what recovering it must do.

PublishOutcome

How a publication ended.

Retention

What became of a branch whose publication did not land.

Scope

Which preserved work to look for.

SlotOutcome

What became of one slot.

SlotState

Where one slot is in its life, as pool status reports it.

Source

The library that produced an event.

Constants

HOST_PREREQUISITE_MARKER

How a merge-path hook begins the one line saying a refusal is this host’s rather than the work’s: a tool or a credential it needs is missing, and what follows the marker says which and how to install it.

Traits

Hosting

Where a RemoteHost for one repository comes from.

PhaseOf

The phase an event of one of this crate’s kinds belongs to, where the kind alone decides it.

RemoteHost

Everything onevcs asks of a repository’s remote host.

Vcs

Everything onevcs does to a repository, independent of which version control system is underneath.

Functions

acknowledge_release

Record the release somebody says carries a landing.

adoption_for

Which rung of the adoption chain one repository resolves to.

close_session

Release a session’s worktree and its occupancy lease, keeping its branch.

describe_change

Replace the description of the session’s own change request — its body, and its title when one is given — and report the change as it stands after the write.

landing_status

Whether one piece of work reached its base, and what says so.

pool_maintain

Maintain the idle slots of every identity in scope.

pool_prune

Remove every slot of one repository nobody is in — idle, or broken — whose clone retains no branch, and say why each other one was kept.

pool_status

The pool of one repository: its capacity with no per-open override, and every slot.

preserve

Put an unpublished branch on its identity’s origin, under its own name, without publishing it.

publish

Verify a session’s work and publish it, returning what the publication did.

read_release_declaration

What one repository declares that it publishes.

ready_change

Mark the session’s own change request ready for review, and report it as it stands.

recoverable

Every preserved-but-unpublished branch in scope, and what would land each.

release_discovery

Every target one repository has, and what each of them has released right now.

release_latest

What version of one target is released right now.

release_status

Whether the release that carries one landed change has happened yet.

release_targets

What one repository releases, and what it adopts.

render_release_declaration

Render a declaration back as the TOML document it declares.

run

Run one parsed command line, returning the process exit code.

run_with

Run one parsed command line against supplied implementations of the two interfaces, returning the process exit code.

session

What the repository side recorded about a session.

session_change

The session’s own change request — the one publish would open or adopt for it, from its branch into the base its publication resolves — as the host holds it, or None when the host holds none.

session_holders

Every session recorded for one repository, live or not, in token order.

validate_release_declaration

Validate one release declaration’s text, and answer what it declares.

workspace_capacity

How many sessions the request’s identity admits right now, and whether the request itself would be placed.

Type Aliases

Envelope

One event of the agent stack: the core’s envelope over the agent vocabulary.

EventFilter

Which envelopes pass: the core’s filter over the agent vocabulary.

EventMatcher

One matcher of an EventFilter: source, kind, and the MatchFields — phase and the five reserved labels a matcher may name.

Result

The result type every fallible entry point in this crate returns.