delivery

func AdmissionKey ¶

func AdmissionKey(stackID, chunkID string) (string, error)

AdmissionKey derives the stable run invocation key for a chunk run (plan F15): re-admission after a restart resolves to the SAME run, never a duplicate. The key is <stack-id>:<chunk-id> (plan D3, §5a step 3).

func AdmitDeliveryTarget ¶

func AdmitDeliveryTarget(ctx context.Context, git GitRunner, gc GitContext, base, worktreeBaseCommit string) (originURL, targetOriginCommit string, err error)

AdmitDeliveryTarget verifies a fresh delivery-required run's target branch admits, and pins the value delivery-time rewrite detection must compare against later.

The repository must have an origin remote, and the delivery target (base) must exist on that remote and CONTAIN (as an ancestor) the commit the run's worktree started from - the worktree's own source branch does NOT need to equal the target by name. This replaces an older check that required the target to sit at the EXACT SAME commit as the worktree base, which only ever admitted a run started at the target's then-tip.

The containment test fetches the target from the ADMITTED origin URL (never a possibly-stale local refs/heads/<base>), so a target that has advanced beyond what this checkout last saw still admits. When the fetched tip does NOT contain the worktree base, one fallback is tried: the LOCAL refs/heads/<base>, for the ordinary case where the operator committed to the target locally but not yet pushed it (see TestAdmitDeliveryTargetLocalAheadOfOriginAccepted). The fallback accepts only a local ref strictly AHEAD of the fetched origin tip; a DIVERGED local ref (a local rebase, or a target rewritten on origin while this clone was stale) is refused, because the recorded pin would then be unrelated to the worktree base and delivery-time rewrite detection would compare the pin against the same rewritten history it came from.

The returned targetOriginCommit is always the FETCHED origin tip (never the local fallback ref); callers record it as OriginBaseCommit, the pin verifyRemoteBaseAncestry compares a later fetch against.

func AllChunksMerged ¶

func AllChunksMerged(chunks []ChunkPlan, merged map[string]bool) bool

AllChunksMerged reports whether every chunk in the plan is merged.

func ChunkPartIndex ¶

func ChunkPartIndex(chunkID string, order []string) (int, error)

ChunkPartIndex returns the 0-based position of a chunk in dependency order, for the canonical "k/N" stack_part. An id absent from order is an error, not position 0: silently treating an unknown chunk as "first" would mislabel its stack_part and, once cross-wave chunk ids exist, mask a real bug (an id order was built without).

func ChunkRunInputs ¶

func ChunkRunInputs(planInputs map[string]string, chunkID, prBase, stackPart string, plan *ChunkPlan, siblingFiles []string) (map[string]any, map[string]string)

ChunkRunInputs builds the admission inputs and snapshot for one chunk-mode run: the plan run's declared inputs replayed (D3) plus the engine's reserved stack inputs, which win on any name collision. The integration run uses the same shape with an empty stack_part and a nil plan entry. When the chunk's decompose plan entry is given, it rides along as chunk_plan JSON: without it the implement agent sees only the FULL task text and a bare chunk ID, and (live finding, smoke-stack-3chunk-v3) implements the whole task instead of its slice.

func ChunkRunNoDiff ¶

func ChunkRunNoDiff(ctx context.Context, repo workflowledger.Repository, run workflowledger.RunSnapshot) bool

ChunkRunNoDiff reports whether a run settled succeeded with a confirmed no_diff delivery outcome: the intended diff was empty, no PR was created, and the chunk is therefore complete. This requires POSITIVE evidence - an actual "no_diff" delivery record - not merely the absence of pushed evidence: a ListDeliveries read failure or a not-yet-recorded delivery also produce zero pushed records, and misreading either as "confirmed no_diff" durably marks a chunk merged with no PR ever created, silently dropping its content (an adversarial audit found this exact regression). A record that reached pushed/succeeded with a commit SHA always wins over a stale no_diff record from an earlier attempt on the same run.

func CloneInputs ¶

func CloneInputs(inputs map[string]string) map[string]string

CloneInputs returns a shallow copy of inputs, safe for a delivery.Request to own and mutate (checkChunkDiffSize writes InputDeferredFiles into it in place - see stacking.go). Every delivery.Request construction site should pass a clone, never the run snapshot's own Inputs map, so that mutation never leaks into cached ledger state.

func CountUnshippedCommits ¶

func CountUnshippedCommits(ctx context.Context, git GitRunner, gc GitContext, deliveredCommit string) (int, error)

CountUnshippedCommits counts the commits on the current worktree HEAD after deliveredCommit (git rev-list --count deliveredCommit..HEAD): the trailing commits a diff-size repair left on the branch after committing the review-sized slice as deliveredCommit (spec-auto-split-oversized-prs.md §5.2-5.3). Zero means no trailing commits: the repair produced exactly one delivered slice and nothing else. Shared by the delivery engine (to record DeliveryRecord.StackRemainingCommits after a successful re-delivery) and by the driver's follow-up chunk admission (§5.3), so both count identically.

func DecomposedChunks ¶

func DecomposedChunks(ctx context.Context, repo workflowledger.Repository, runID string) (chunks int, ok bool)

DecomposedChunks reports whether runID is the plan run of a multi-chunk stack: the LATEST succeeded decompose step attempt that produced an output parses as mode=multi with at least one chunk (same selection rule as LoadStackPlanOutput and the controller's latestOutputAttempt; a later succeeded attempt with no output must not shadow the recorded plan). ok=false covers every other case (not a stacking plan run, single/no_bug, a malformed decompose output, or a lookup failure) - callers must treat a lookup failure as "not applicable", never as a refusal or a false "undriven" diagnostic.

func DeferredBranchName ¶

func DeferredBranchName(branch string) string

DeferredBranchName derives the local branch name a split delivery (freshDeliveryCommitSplit) saves its deferred commit under, deterministic from the chunk's own delivery branch so no extra ledger field is needed to find it afterward: the driver (internal/cli) computes the same name to look it up and push it as a follow-up PR after this chunk's delivery succeeds. resumeDeliveryCommitSplit re-creates the same branch from the recorded DeferredFiles when a split attempt crashed after C1, so the name is also the resume contract between the delivery engine and the driver.

func DeliveryKey ¶

func DeliveryKey(runID, workflowDigest string) string

DeliveryKey derives the stable idempotency key for one run's delivery from admitted data only: sha256(runID + NUL + workflowDigest), hex-encoded, prefixed wfdel:.

func EffectiveBase ¶

func EffectiveBase(wf *definition.CompiledWorkflow, inputSnapshot map[string]string) string

EffectiveBase returns the delivery base a fresh admission must guard: a valid pr_base input overrides the workflow's declared delivery base (the same override delivery honors at publish time, resolveStackingInputs), so the admission origin-containment check keys off the branch the run will actually deliver to. An absent, empty, or invalid pr_base never fails admission — the declared base is used instead. inputSnapshot may be nil; a nil or non-delivery workflow yields the declared base or "".

func FormatOutcome ¶

func FormatOutcome(r Result, err error) string

FormatOutcome renders the human-readable CLI summary of one delivery attempt. A successful or no_diff result is described from r; a refusal is permanent; any other error is a transient attempt failure that can be retried.

func HasDeferredFollowUp ¶

func HasDeferredFollowUp(ctx context.Context, repo ledger.Repository, runID string) bool

HasDeferredFollowUp reports whether runID's most recent succeeded delivery record left a pending deferred commit (DeliveryRecord.StackRemainingCommits > 0).

func IntegrationRunInputs ¶

func IntegrationRunInputs(planInputs map[string]string, prBase string) (map[string]any, map[string]string)

IntegrationRunInputs builds the admission inputs for the final full-suite integration run: it replays the plan run's declared inputs and admits as stack_mode=single (running the workflow's own plan+implement steps inline), never stack_mode=chunk. chunk_plan's chunk/pr_base/stack_part are deliberately absent: stack_mode=chunk REQUIRES stack_part present (validateStackingReservedInputs), and the integration run has none - a bug an adversarial audit found: chunkRunInputs forced stack_mode=chunk here with an always-empty stack_part, so every stack's integration run failed admission the moment every chunk merged.

func IsAncestryUnverifiable ¶

func IsAncestryUnverifiable(err error) bool

IsAncestryUnverifiable reports whether err is an AncestryUnverifiableError (possibly wrapped).

func IsCommitMessageRejection ¶

func IsCommitMessageRejection(cause error) bool

IsCommitMessageRejection reports whether cause is a git commit failure whose output names the workspace commit-msg hook (git runs that hook after the message is written, so its diagnostics appear in the commit error text). The rejected artifact is the commit MESSAGE, not the worktree: the subject is the agent's pr_title and the body is rendered from the workflow's commit_message_template, so the repair is a structured-output edit, not a worktree edit. Requiring the git failure marker keeps the classifier off any text that merely mentions a commit-msg hook without a failed commit.

func IsDiffSizeError ¶

func IsDiffSizeError(err error) bool

IsDiffSizeError reports whether err is a DiffSizeError (possibly wrapped).

func IsPRMetadataError ¶

func IsPRMetadataError(err error) bool

IsPRMetadataError reports whether err is a PRMetadataError (possibly wrapped).

func IsPermanentMergeError ¶

func IsPermanentMergeError(err error) bool

IsPermanentMergeError reports whether err from MergePullRequest represents a failure that retrying will never fix: the PR is closed, auth is broken, a branch was deleted, or a merge conflict exists. Retriable conditions (pending CI, review requirements, transient gh errors) return false so the caller can keep polling.

func IsRefusal ¶

func IsRefusal(err error) bool

IsRefusal reports whether err is a RefusalError (possibly wrapped).

func IsTransportFault ¶

func IsTransportFault(err error) bool

IsTransportFault reports whether err is a git/gh transport fault: a wrapped net/syscall error of the connection-death kinds, or an error whose text carries one of the transport fault phrases. It never matches a bare context deadline or cancellation.

func LatestFailureText ¶

func LatestFailureText(ctx context.Context, repo ledger.Repository, runID string) (string, error)

LatestFailureText returns the stored failure text of the latest wf-delivery repair attempt that carries an error ref, or "" when none exists. The attempt with the highest AttemptNo wins; a later attempt in event order wins a tie. Only a storage or load failure is an error.

func LoadStackPlanOutput ¶

func LoadStackPlanOutput(ctx context.Context, repo workflowledger.Repository, stackID string) ([]byte, error)

LoadStackPlanOutput reads the succeeded decompose step output of a plan-mode run from the run ledger (F1/F8: the plan is a run output). When the plan run's decompose step ran more than once, the LATEST succeeded attempt that produced an output is authoritative.

func LoadTemplates ¶

func LoadTemplates(baseDir string) (map[string]string, error)

LoadTemplates reads all .md files from the given directory. Returns a map of basename -> content, or an error if the directory is invalid. Path traversal is rejected: all resolved paths must remain under baseDir.

func MeasureChunkDiffSize ¶

func MeasureChunkDiffSize(ctx context.Context, git GitRunner, gc GitContext, baseCommit string, hard int, excludePaths []string) (int, error)

MeasureChunkDiffSize measures the actual added+deleted line count of the staged worktree diff vs base, using the same staging and numstat rules the delivery gate applies (--find-renames, --ignore-all-space, untracked files included via git add -A). hard <= 0 means the gate is off and 0 is returned without touching git. excludePaths, when non-empty, excludes those workspace-relative paths from the measured diff via a pathspec exclusion (spec-auto-split-oversized-prs.md §5.2: a repair's deferred_files are committed separately and must not count against the delivered diff's own size). It is shared by the delivery gate and the controller's post-implement fail-fast gate so both measure identically; the controller's gate always passes nil (deferred_files is a repair-time decision, unknown that early).

func MergePullRequest ¶

func MergePullRequest(ctx context.Context, repo, number string, draft bool) error

MergePullRequest merges the PR identified by number in repo (owner/repo). draft=true marks the PR ready for review first. It returns nil once the merge command succeeded (the PR is merged now, or enqueued on a merge queue); a non-nil error means the PR is not mergeable yet and the caller should retry later.

func MergedSet ¶

func MergedSet(byID map[string]workflowledger.Task) map[string]bool

MergedSet returns the set of chunk ids whose tasks are merged.

func PRBase ¶

func PRBase(wf *definition.CompiledWorkflow) (string, error)

PRBase returns the delivery base branch the chunk PRs branch from: the workflow's delivery policy base (delivery honors pr_base, S4).

func ParseDeferredFiles ¶

func ParseDeferredFiles(raw string) ([]string, error)

ParseDeferredFiles decodes the InputDeferredFiles reserved input: a JSON-encoded array of workspace-relative paths, or "" (no deferral). A present-but-malformed value is a repairable PRMetadataError (the engine's own read of the repair step's output was well-formed JSON matching the schema; a malformed value here means something upstream corrupted it, which is worth surfacing as a repair-loop-visible failure rather than silently ignoring the split decision).

func ParseOwnerRepo ¶

func ParseOwnerRepo(url string) (string, error)

ParseOwnerRepo normalizes a git remote URL to owner/repo. It supports the https, scp-like git@, and ssh:// forms. The host must be github.com (case-insensitive) and the path must be exactly owner/repo with an optional trailing .git.

func PlanInputs ¶

func PlanInputs(ctx context.Context, repo workflowledger.Repository, stackID string) (map[string]string, error)

PlanInputs reads the plan run's admitted snapshot and returns the workflow-declared inputs the chunks were decomposed from, so chunk runs can replay them (D3: chunk runs replay the plan run's inputs). The plan run's own RunID IS the stack id; it was never admitted with a "<stack>:<chunk>" key, so it is read directly by RunID.

func ProbePRTool ¶

func ProbePRTool(provider string) error

ProbePRTool reports whether the provider's PR tool is usable before a run starts.

Delivery is the last step of a long workflow, so a missing tool is only discovered after every gate has passed and the whole run is spent. The probe moves that discovery to admission.

It is deliberately OFFLINE. `gh --version` touches no network and proves the binary exists and executes. An auth probe was considered and rejected: it would put a network call in the admission path of every delivery run, and it still could not prove the token is valid at delivery time, which may be hours later. Delivery keeps its own authoritative checks.

func Render ¶

func Render(source string, inputs, evidence map[string]any, maxBindingBytes, maxRenderedBytes int) (string, error)

Render expands only explicit input and evidence bindings. It does not read files, execute commands, or inspect an agent transcript.

A successful render is always valid UTF-8: the template source and every string binding value must be valid UTF-8 (refused otherwise), and non-string binding values are JSON-encoded and the encoded bytes validated as UTF-8 (refused otherwise), because a value implementing json.Marshaler can carry invalid bytes that json.Marshal copies verbatim. Rendered output is bounded by maxRenderedBytes and each encoded binding by maxBindingBytes; zero or negative limits select the package defaults.

func ReopenForRepair ¶

func ReopenForRepair(ctx context.Context, repo ledger.Repository, runID, repairStep string, maxRepairs int, cause error, stdout io.Writer) error

ReopenForRepair returns a run whose delivery failed to the step the workflow names in delivery.on_failure (or the PR-metadata/diff-size variants; delivery.RepairTarget is the single classifier both the CLI and the local engine use). maxRepairs bounds the cycle; <=0 selects MaxDeliveryRepairs.

Delivery runs after the success terminal, outside the step graph, so a repairable delivery failure (commit hook rejection is the common case) used to have no route back into the workflow and just waited for a person.

The re-entry writes the delivery attempt and its TERMINAL failure outcome with a route to the repair step in ONE durable event, so the attempt is never observable non-terminal — a crash before the write leaves nothing durable changed (run returns to delivery via reconcile); a crash after leaves it already terminal with the repair route. Either way is recoverable. The ledger derives the active step from the last attempt's route, so the run continues at the repair step on next resume. Failure evidence (RepairHint: what to repair, whether a commit is involved) is stored content-addressed and referenced by the attempt, so the repair agent reads why delivery failed instead of guessing.

Nothing here knows what the failure was or which step repairs it — the workflow author names the step, so the mechanism stays generic.

func RepairHint ¶

func RepairHint(cause error) string

RepairHint renders the harness guidance a repair agent needs to fix a delivery rejection: a short "what to repair" line derived from the failure class, then the raw rejection text. It is project- and language-agnostic: it never names a repository's tests, files, tools, or gate names, so it is safe to ship in the binary and render for any workspace.

The hint is the deterministic evidence a delivery re-entry step sees via delivery.failure. Without a class-specific lead the agent has to guess what to repair from a wall of hook output; with it, the agent is told up front whether the failure is a gate rejection of the change, a PR-metadata defect, an over-limit diff, or a permanent host refusal - and, when a commit is involved, that the host commits the repaired worktree before the next delivery attempt.

func RepairTarget ¶

func RepairTarget(err error, p Policy) string

RepairTarget returns the delivery repair step the policy names for a failure class. Diff-size rejections route to OnDiffSizeFailure (falling back to OnFailure), PR-metadata rejections to OnPRMetadataFailure (falling back to OnFailure), and every other repairable rejection to OnFailure. An AncestryUnverifiableError (git itself could not complete the base-ancestry check - a missing or corrupt object) yields an empty result unconditionally: no agent can repair a git object failure, so the run stays delivery_pending with a recorded cause and a later attempt retries. An empty result otherwise means the workflow declares no repair route for the class (the run holds for a person). It is the single classifier shared by the CLI and the local engine, so a delivery rejection routes to the same step on both paths.

func ResolveLatestChangeSummary ¶

func ResolveLatestChangeSummary(ctx context.Context, repo ledger.Repository, runID string) (map[string]any, error)

ResolveLatestChangeSummary returns the change-summary object of the latest attempt whose output is a JSON object carrying a non-empty string "pr_title" key, or nil when none exists. "Latest" is GLOBAL event order: the attempt that most recently recorded a change summary wins. Per-step AttemptNo is NOT comparable across steps - a repair step that re-ran after an implement step always has a lower AttemptNo than implement's later attempt even though it happened after it - so the attempt with the latest StartedAt wins, and a later attempt in event order wins a tie (including all-zero synthetic fixtures). Only schema-validated outputs ever carry an OutputRef, so the presence of pr_title marks a change summary. Only a storage or load failure is an error; an output that is not valid JSON is skipped.

func RunHeadCommit ¶

func RunHeadCommit(ctx context.Context, repo workflowledger.Repository, run workflowledger.RunSnapshot) string

RunHeadCommit returns the pushed commit SHA for a chunk run, if any. The commit is the durable evidence the merge oracle uses to verify that the base branch contains the change.

func RunPushed ¶

func RunPushed(ctx context.Context, repo workflowledger.Repository, run workflowledger.RunSnapshot) bool

RunPushed reports durable pushed evidence for a chunk run: any of its delivery records reached pushed/succeeded with a commit SHA. A record in that state is only written after the branch was actually pushed to origin (the deliverer writes pushed after the push, succeeded after the PR is created). Without this evidence a missing remote ref means "never pushed", not "merged" - a delivery_pending run's PR may never have been created.

func Scope ¶

func Scope(stackID string) workflowledger.Scope

Scope binds every stack task to the plan run that produced the chunk plan, so queries never cross stacks (D8 scope binding).

func SeedStackLedger ¶

func SeedStackLedger(ctx context.Context, ledger *workflowledger.Store, stackID string, chunks []ChunkPlan) error

SeedStackLedger records the plan artifact and the chunk tasks (D8). Re-entry is idempotent: existing tasks are left untouched (their durable status wins - a re-drive after a partial completion, a continuation-wave seed, or the recovery sweep must never overwrite or re-create them), and only missing tasks are created. A lost race against a concurrent seed is also a no-op (the other writer won).

func SentenceCount ¶

func SentenceCount(s string) int

SentenceCount counts the sentence boundaries in s. The rule is deterministic: a sentence boundary is a terminator ('.', '!', '?') followed by whitespace and an uppercase letter, or followed by end of text. The function counts boundaries on the trimmed text. Empty text has zero sentences. The rule handles abbreviations and version numbers correctly: 'e.g.', 'v1.2.3', and 'U.S.' do not split a sentence because their terminators are not followed by whitespace and an uppercase letter.

func SiblingFiles ¶

func SiblingFiles(chunks map[string]*ChunkPlan, chunkID string) []string

SiblingFiles returns the union of the declared files of every chunk except the named one, sorted for a deterministic input digest. The union covers the chunks known at admission; later decompose waves are not visible to already-admitted chunk runs, which keep the directory heuristic inside the engine.

func StatusIsAdmissiblePre ¶

func StatusIsAdmissiblePre(status string) bool

StatusIsAdmissiblePre reports whether status is one a drive pass treats as "not yet admitted."

func StatusIsTerminal ¶

func StatusIsTerminal(status string) bool

StatusIsTerminal reports whether status is one a drive pass must leave alone.

func StoreDeliveryFailureText ¶

func StoreDeliveryFailureText(ctx context.Context, repo ledger.Repository, cause error) string

StoreDeliveryFailureText puts the harness repair hint (RepairHint) in content-addressed storage and returns its ref. Fail-soft: an empty ref costs the repair agent its evidence, but must not stop the re-entry.

func TaskMap ¶

func TaskMap(ctx context.Context, ledger *workflowledger.Store, stackID string) (map[string]workflowledger.Task, error)

TaskMap loads every stack task by id for a drive pass.

func TaskReady ¶

func TaskReady(t workflowledger.Task, merged map[string]bool) bool

TaskReady reports whether a task's dependencies are all merged.

func TopologicalOrder ¶

func TopologicalOrder(chunks []ChunkPlan) ([]string, error)

TopologicalOrder returns chunk ids in admission order (dependencies first) using Kahn's algorithm. Unknown, duplicated, or cyclic dependencies are errors: a stack must never admit a chunk before the chunks it depends on, and a duplicated id must never emit a duplicated admission order. Without the duplicate check, two chunks sharing a zero-indegree id both land in the ready queue, the loop emits the id twice, len(order) == len(chunks) still holds, and the driver silently gets a wrong order: duplicated wave entries, inflated "k/N" stack_part labels (ChunkPartIndex returns the first occurrence), and admission of the same chunk twice. The deterministic chunk-plan gate rejects duplicate ids per wave, but a continuation wave can reuse an id from an earlier wave (loadAllStackChunks concatenates the waves), so the shared ordering must fail closed on its own.

func ValidatePRBase ¶

func ValidatePRBase(name string) error

ValidatePRBase validates a pr_base value (a git branch name): the allowed characters are A-Za-z0-9._/-, the value is at most 100 characters, does not start with '-' (a git option-injection guard), and does not contain '..' (a ref-traversal guard). Every violation is a repairable PRMetadataError naming the problem, so the repair loop can fix the input.

func ValidateReferences ¶

func ValidateReferences(loaded map[string]string, stepTemplates []string) []string

ValidateReferences checks that all template references in stepTemplates exist in the loaded templates map. Returns a list of missing template names.

func VerifyGitDir ¶

func VerifyGitDir(ctx context.Context, mainRoot, worktreeName, worktreeDir string) (string, error)

VerifyGitDir validates the worktree's .git file and returns the real git directory. It refuses a missing, symlinked, or misdirected .git file.