delivery

Documentation

Overview

Package delivery checks, against local git, the delivery claims a harness session makes to the control plane.

The plane is a pipe: it holds the backlog and takes a clanker at its word. When a session records a branch or declares a commit merged, nothing verifies either claim — and one task (CLA-134) read `done` for four days while ~900 lines of its work sat unpushed on one laptop, its own PR merging a stale snapshot.

The driver is the right place to close that: it is already local, already in the git tree, and already watches the session stream for `claim_task` and `update_task` (CLA-242). This adds a check to an observation that already happens. It needs no new credentials and no plane change.

Fail open, not closed

Every check has three outcomes, not two: Pass, Fail, and Unknown. Unknown is load-bearing. If the check cannot run — no git on PATH, no remote, a workdir that is not a repository, a remote tip we do not have locally — the answer is "could not verify", never "verified". A driver that reported a false pass would be worse than the gap it replaces, and one that blocked a legitimate closure because it could not find the tree would be worse still. Not knowing is not the same as knowing it is fine, and neither is grounds for overriding the session.

Which working tree

The driver spawns sessions in a workdir, but the work happens in a per-task worktree the driver did not create and does not track — and the workdir is routinely a multi-repo parent (`~/dev`) that is not a repository at all.

The resolution is narrower than it first looks: linked worktrees SHARE the repository's ref database, so the specific directory a session worked in is irrelevant. Every check here reads refs (`refs/heads/<branch>`, `ls-remote`, `merge-base`), so any working tree of the right repository answers identically. What must be found is the REPOSITORY whose refs carry the branch, which is a bounded search of the workdir and its first two directory levels — enough to reach both `~/dev/<repo>` and `~/dev/<repo>-wt/<task>`. A repository is never descended into, so a tree of worktrees costs one probe, not one per worktree.

Index

• func Remote(ctx context.Context, repo, preferred string) string
• func Repos(ctx context.Context, workdir string) []string
• type Check
• type Claim
  • func (c Claim) Empty() bool
• type Kind
• type Report
  • func (r Report) Failed() bool
  • func (r Report) MergeVerified() (verified, ran bool)
• type Status
• type Verifier
  • func New(workdir, remote string) *Verifier
  • func (v *Verifier) Verify(ctx context.Context, c Claim) Report

Functions

func Remote

func Remote(ctx context.Context, repo, preferred string) string

Remote picks the remote to act on in repo: the preferred one when the repository has it, otherwise its only remote. Shared with salvage for the same reason as Repos - a rescue has to push to the remote these checks will then judge it against. The workdir plays no part in this one, hence the empty one.

func Repos

func Repos(ctx context.Context, workdir string) []string

Repos lists one working tree per distinct git repository at or below workdir - the search described in this package's doc, exposed for the driver's salvage path (CLA-314).

It is shared rather than reimplemented because salvage has to find the SAME repository these checks do. Two implementations of "which tree did the session work in" would agree until the day they did not, and on that day one of them would be committing.

Types

type Check

type Check struct {
	Kind   Kind
	Status Status
	// Detail is written to be read in a log at 3am by someone who was asleep when
	// it happened: it names what is unpushed or unmerged, not just that something
	// is wrong.
	Detail string
}

Check is one verified (or unverifiable) assertion.

type Claim

type Claim struct {
	// Label identifies the task in logs ("CLA-253"); cosmetic.
	Label string

	// Branch is the work-in-progress branch recorded as the handover record.
	Branch string

	// Commit and IntegrationBranch are the declared delivery: the commit that
	// carried the work, and the branch it is claimed to have landed on.
	Commit            string
	IntegrationBranch string
}

Claim is what a session told the plane it delivered.

func (Claim) Empty

func (c Claim) Empty() bool

Empty reports that there is nothing here to check.

type Kind

type Kind string

Kind names which claim a check was about.

const (
	// BranchPushed: a branch recorded via `update_task(branch: ...)` is really on
	// the remote, and the local tip is an ancestor of the remote tip.
	BranchPushed Kind = "branch"
	// CommitMerged: a declared `delivery.commit` is an ancestor of the declared
	// `delivery.integrationBranch`.
	CommitMerged Kind = "merge"
)

type Report

type Report struct {
	Claim Claim
	// Repo is the working tree the checks ran in. Empty when none was resolved.
	Repo   string
	Checks []Check
}

Report is everything the driver learned about one session's delivery claim.

func (Report) Failed

func (r Report) Failed() bool

Failed reports whether any check ran and came back false. Unknown is not a failure — it is an absence of knowledge.

func (Report) MergeVerified

func (r Report) MergeVerified() (verified, ran bool)

MergeVerified reports what the merge check concluded: (verified, ran). When ran is false the driver must not attest anything — an honest `mergeVerified` is only written for a check that actually happened.

type Status

type Status string

Status is the outcome of one check. The three-way split is the whole point: see the package doc on failing open.

const (
	// Pass: the check ran and the claim holds.
	Pass Status = "pass"
	// Fail: the check ran and the claim does not hold. This is the CLA-134 case.
	Fail Status = "fail"
	// Unknown: the check could not run. NOT a pass.
	Unknown Status = "unknown"
)

type Verifier

type Verifier struct {
	// contains filtered or unexported fields
}

Verifier checks delivery claims against the git repositories under a workdir. The zero value is not usable; build one with New.

func New

func New(workdir, remote string) *Verifier

New builds a Verifier rooted at a session's workdir. remote is the git remote the claims are judged against; empty means "origin, or the only remote there is".

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, c Claim) Report

Verify checks a claim and returns what it found. It never returns an error: everything that could go wrong is a check whose Status is Unknown, because the caller's only correct response to "could not check" is to say so and carry on.