streamsync

type AgentBranch struct {
	Branch string `json:"branch"`
	// Agent is the claiming session, so a conflict report can name who has to
	// resolve it.
	Agent string `json:"agent,omitempty"`
	// InReview marks a branch whose review is open. Rebasing it invalidates
	// the review, so sync refuses by default.
	InReview bool `json:"in_review,omitempty"`
}

type BatchResult struct {
	Passed bool `json:"passed"`
	// Runs is how many full verification runs it cost. One in the passing
	// case; 1+k when the culprit is element k.
	Runs int `json:"runs"`
	// Elements is the batch as applied, after lockstep families are grouped.
	Elements []Element `json:"elements"`
	// Culprit is the last element of the first failing prefix.
	Culprit *Element `json:"culprit,omitempty"`
	// ProvenGood are the elements every failing prefix had already cleared.
	ProvenGood []Element `json:"proven_good,omitempty"`
	// InteractionFailure is set when every prefix passed: the failure came
	// from the base or a rebased change, not from any element.
	InteractionFailure bool `json:"interaction_failure,omitempty"`
	// FailingCheck names what actually failed.
	FailingCheck string `json:"failing_check,omitempty"`
	// Skipped names CI mechanisms this run did not execute, printed only
	// where CI is proved to carry them.
	Skipped []string `json:"skipped,omitempty"`
	// Unguarded names mechanisms neither this run nor CI carries.
	Unguarded []string `json:"unguarded,omitempty"`
	// Unverified names mechanisms WB could not decide about, because the
	// stream-PR workflow calls a reusable workflow in another repository.
	// "I could not tell" is not the same claim as "CI does not run it".
	Unverified []string `json:"unverified,omitempty"`
	// UnexaminedElements is how many elements the prefix scan never reached.
	// The scan stops at the FIRST failing prefix by design, so a green re-run
	// after fixing the culprit is expected rather than surprising.
	UnexaminedElements int `json:"unexamined_elements,omitempty"`
	// ScratchBranch is the local branch prefix re-apply ran on. It is never
	// pushed, which is what keeps the whole search to zero CI runs.
	ScratchBranch string `json:"scratch_branch,omitempty"`
}

type BumpResult struct {
	Library Library `json:"library"`
	// Action is one of the Bump* constants.
	Action string `json:"action"`
	// Required is the version the consumer required after the rebase.
	Required string `json:"required,omitempty"`
	Commit   string `json:"commit,omitempty"`
	Detail   string `json:"detail,omitempty"`
}

type Bumper interface {
	// Required reports the version the consumer currently requires for one
	// library, after the rebase. found=false means the consumer does not
	// declare it at all.
	Required(ctx context.Context, dir string, library Library) (version string, found bool, err error)
	// Apply updates the manifests and lockfiles to target. It must run the
	// toolchain that refreshes go.sum / pnpm-lock.yaml, and it must not
	// commit — the engine owns the commit so the message follows the
	// repository's convention and so a no-op leaves no commit behind.
	Apply(ctx context.Context, dir string, library Library) error
}

type CIMechanisms interface {
	// Present reports which mechanisms the stream-PR workflows carry, and
	// whether any of them calls a REUSABLE workflow whose body WB cannot
	// read. An opaque callee makes a mechanism unverified, never absent.
	Present(dir string) (mechanisms map[string]bool, opaque bool, err error)
}

type Element struct {
	Name        string `json:"name"`
	SHA         string `json:"sha"`
	Description string `json:"description,omitempty"`
	// Family groups a lockstep-versioned set (Angular, Nx, Ionic, Capacitor,
	// @sneat/*) that must be applied together and never split during prefix
	// re-apply.
	Family string `json:"family,omitempty"`
	// contains filtered or unexported fields
}

type Engine struct {
	Git      Git
	Bumper   Bumper
	Verifier Verifier
	CI       CIMechanisms
	Events   Events
	Now      func() time.Time
}

type Event struct {
	Stream     string            `json:"stream"`
	Verb       string            `json:"verb"`
	Phase      string            `json:"phase,omitempty"`
	Repository string            `json:"repository,omitempty"`
	Outcome    string            `json:"outcome"`
	Detail     string            `json:"detail,omitempty"`
	Evidence   map[string]string `json:"evidence,omitempty"`
}

type Events interface {
	Append(event Event) error
}

type ExecBumper struct{ Timeout time.Duration }

type ExecGit struct{ Timeout time.Duration }

type Git interface {
	// Fetch refreshes origin. Sync rebases onto a freshly fetched base, never
	// onto whatever the local clone happens to hold.
	Fetch(ctx context.Context, dir string) error
	// FastForwardToRemote advances branch only when the fetched remote branch
	// contains it. It never rewrites local commits or resolves a divergence;
	// callers receive the fetched remote head so its lease can be refreshed.
	FastForwardToRemote(ctx context.Context, dir, branch, remote string) (remoteHead string, present, advanced bool, err error)
	// CurrentBranch reports the checked-out branch.
	CurrentBranch(ctx context.Context, dir string) (string, error)
	// Rebase replays branch onto upstream. It reports the conflicting paths
	// rather than leaving the worktree mid-rebase: a conflict in one agent's
	// branch must not abort the others, so the caller needs the conflict as
	// data and the tree back in a usable state.
	Rebase(ctx context.Context, dir, branch, upstream string) (conflicts []string, err error)
	// AbortRebase restores the tree after a conflicted rebase.
	AbortRebase(ctx context.Context, dir string) error
	// Head resolves a revision to a SHA.
	Head(ctx context.Context, dir, revision string) (string, error)
	// CommitsAhead counts commits on branch that upstream does not carry.
	CommitsAhead(ctx context.Context, dir, branch, upstream string) (int, error)
	// CommitAll stages every change and writes one commit. It returns the new
	// SHA, and ok=false when there was nothing to commit — which is what makes
	// a re-run of sync produce no new commits.
	CommitAll(ctx context.Context, dir, message string) (sha string, ok bool, err error)
	// CreateBranch points a new branch at a revision, replacing it if it
	// exists. Prefix re-apply runs on one of these and it is never pushed.
	CreateBranch(ctx context.Context, dir, branch, revision string) error
	// Checkout switches the worktree to a branch.
	Checkout(ctx context.Context, dir, branch string) error
	// ResetHard moves the current branch to a revision, discarding changes.
	ResetHard(ctx context.Context, dir, revision string) error
	// CherryPick applies one commit onto the current branch.
	CherryPick(ctx context.Context, dir, sha string) error
	// DeleteBranch removes a local branch.
	DeleteBranch(ctx context.Context, dir, branch string) error
	// IsClean reports whether the worktree has no uncommitted change.
	IsClean(ctx context.Context, dir string) (bool, error)
	// RestoreTo discards every change and returns the worktree to a revision.
	// A bump whose lockfile refresh failed must not be left half-applied.
	RestoreTo(ctx context.Context, dir, revision string) error
	// PushWithLease publishes branch using --force-with-lease against the head
	// WB last recorded, and verifies the ref it pushed. A rebase of a shared
	// branch is a force-push, and a bare force discards whatever another agent
	// pushed in between.
	PushWithLease(ctx context.Context, dir, branch, expectedRemoteHead string) (sha string, err error)
}

type Library struct {
	// Name is the module path or package name.
	Name string `json:"name"`
	// Target is the version the consumer should require.
	Target string `json:"target"`
	// Ecosystem is "go" or "npm"; it selects the commit-message convention.
	Ecosystem string `json:"ecosystem"`
}

type Options struct {
	Stream string
	// Worktree is the stream worktree the bumps are applied in. Bumps need a
	// checkout because the toolchain has to refresh go.sum / pnpm-lock.yaml.
	Worktree string
	// Repository is the member being synced, for reporting.
	Repository string
	// Branch is `stream/<name>`; Base is what it rebases onto.
	Branch string
	Base   string
	// Libraries are the own-library targets in scope for this sync.
	Libraries []Library
	// AgentBranches are the stream's open agent branches.
	AgentBranches []AgentBranch
	// Verify runs the batch verification after applying.
	Verify bool
	// AllowMidReview proceeds past a branch whose review is open, with a
	// warning. Rebasing it invalidates that review.
	AllowMidReview bool
	// PushTrigger and PushReason justify a push. Empty means no push, which
	// is the normal outcome: sync's whole point is that bumps stay local.
	// A justified trigger performs a REAL push, verified against the remote.
	PushTrigger PushTrigger
	PushReason  string
	// RecordedRemoteHead is the stream head WB last recorded, used as the
	// --force-with-lease expectation.
	RecordedRemoteHead string
	// Timeout bounds each verification run.
	Timeout time.Duration
}

type PushDecision struct {
	Trigger PushTrigger `json:"trigger"`
	Reason  string      `json:"reason"`
	// SHA is what origin holds after the push. It is set only once the push
	// has been verified, so a caller reading this field is reading an effect
	// rather than an intention.
	SHA string `json:"sha,omitempty"`
}

type PushTrigger string

type RebaseResult struct {
	Branch    string   `json:"branch"`
	Agent     string   `json:"agent,omitempty"`
	Rebased   bool     `json:"rebased"`
	Conflicts []string `json:"conflicts,omitempty"`
	Detail    string   `json:"detail,omitempty"`
}

type Refusal struct {
	Code       string
	Message    string
	Sanctioned []string
}

type Result struct {
	Stream     string `json:"stream"`
	Repository string `json:"repository"`
	// RecordedRemoteHead is the fetched stream branch head that the caller
	// must persist for a later --force-with-lease. It is deliberately the
	// remote head, not an unpushed local rebase or dependency bump.
	RecordedRemoteHead string `json:"recorded_remote_head,omitempty"`
	// RemoteAdvanced reports that the clean checkout was fast-forwarded to a
	// newer remote stream head before its ordinary rebase onto the base.
	RemoteAdvanced bool `json:"remote_advanced,omitempty"`
	// BaseBefore and BaseAfter show what the rebase moved onto.
	BaseBefore string `json:"base_before,omitempty"`
	BaseAfter  string `json:"base_after,omitempty"`
	// StreamRebase is the stream branch's own rebase onto the base.
	StreamRebase RebaseResult `json:"stream_rebase"`
	// AgentRebases are the agent branches, reported per branch: a conflict in
	// one must not stop the others.
	AgentRebases []RebaseResult `json:"agent_rebases,omitempty"`
	Bumps        []BumpResult   `json:"bumps"`
	// Batch is the single verification over the resulting tree.
	Batch *BatchResult `json:"batch,omitempty"`
	// Unpushed is what the operator sees accumulating locally.
	Unpushed UnpushedReport `json:"unpushed"`
	// Push is set only when a trigger justified one AND the push landed. It
	// carries the SHA the remote actually holds.
	Push *PushDecision `json:"push,omitempty"`
	// PushSkipped states, in words, that the remote was left untouched.
	PushSkipped string   `json:"push_skipped,omitempty"`
	Errors      []string `json:"errors,omitempty"`
}

type UnpushedReport struct {
	Repository string `json:"repository"`
	Branch     string `json:"branch"`
	Commits    int    `json:"commits"`
}

type VerificationRun struct {
	Passed  bool     `json:"passed"`
	Command string   `json:"command,omitempty"`
	Details []string `json:"details,omitempty"`
	// Skipped names each CI mechanism this run did not execute. It is only
	// ever printed alongside evidence that CI actually carries it.
	Skipped []string `json:"skipped,omitempty"`
	// Duration is the wall time, so a boundary's cost is measurable rather
	// than remembered.
	Duration time.Duration `json:"-"`
}

type Verifier interface {
	// Verify runs the full suite once over the tree as it stands.
	Verify(ctx context.Context, dir string) (VerificationRun, error)
}