streams

type AgentPullRequest struct {
	Repository string `json:"repository"`
	Number     int    `json:"number"`
	URL        string `json:"url"`
	Title      string `json:"title"`
	Head       string `json:"head"`
}

type AgentPullRequestOutcome struct {
	Repository string `json:"repository"`
	Number     int    `json:"number"`
	URL        string `json:"url"`
	Action     string `json:"action"`
	Detail     string `json:"detail,omitempty"`
}

type Commit struct {
	SHA     string `json:"sha"`
	Subject string `json:"subject"`
	// PatchID is `git patch-id --stable` over the commit's diff. It is empty
	// only when Git could not produce one (an empty commit, for example), and
	// an empty value is never treated as equal to another empty value.
	PatchID string `json:"patch_id,omitempty"`
}

type ConsumerBehind struct {
	Repository string `json:"repository"`
	Identity   string `json:"identity"`
	Manifest   string `json:"manifest"`
	Declared   string `json:"declared"`
	Published  string `json:"published"`
}

type CreatedWorktree struct {
	Repository string
	Worktree   string
	Canonical  string
	Branch     string
	Base       string
}

type Declaration struct {
	Identity Identity `json:"identity"`
	// Manifest is the consumer-relative manifest that declares it.
	Manifest string `json:"manifest"`
	// Version is exactly as declared, including any range prefix.
	Version string `json:"version"`
	// Section is the canonical dependency section the declaration came from.
	Section string `json:"section,omitempty"`
	// Workspace is the consumer-relative npm workspace that owns Manifest.
	Workspace string `json:"workspace,omitempty"`
}

type DiscardEvents struct{}

type Ecosystem string

type EndMemberResult struct {
	Repository string `json:"repository"`
	Worktree   string `json:"worktree"`
	// RemoteBranchDeleted records that origin/stream/<name> is gone.
	RemoteBranchDeleted bool `json:"remote_branch_deleted"`
	// WorktreeRemoved is true when the existing cleanup path retired it.
	WorktreeRemoved bool `json:"worktree_removed"`
	// LeaseReleased is true when the stream lease record was cleared.
	LeaseReleased bool `json:"lease_released"`
	// DraftPullRequest is the member's own stream pull request, reported
	// rather than merged: ending a stream publishes, bumps and merges
	// nothing.
	DraftPullRequest int    `json:"draft_pull_request,omitempty"`
	DraftAction      string `json:"draft_action,omitempty"`
	Detail           string `json:"detail,omitempty"`
}

type EndOptions struct {
	Name string
	// Apply performs the removal. Without it the verb reports exactly what it
	// would do and changes nothing, so an operator can see which agent pull
	// requests would be closed before any of them are.
	Apply bool
	// Retarget moves still-open agent pull requests onto the member's base
	// instead of closing them. The default closes them, because GitHub's own
	// silent retarget is the hazard this verb exists to prevent and doing it
	// deliberately must be an explicit choice.
	Retarget bool
	// ForceUnabsorbed proceeds past the absorption guard. It is not a bypass
	// that hides anything: it requires Reason, records both in the event log,
	// and names every commit it is stepping over. Without it, an absorption
	// check WB could not run refuses — a check that cannot answer must not
	// pass.
	ForceUnabsorbed bool
	// Reason is mandatory with ForceUnabsorbed and is recorded verbatim.
	Reason string
	// KeepRemoteBranch leaves origin/stream/<name> in place. By default end
	// deletes it, because leaving it is scaffolding the verb claims to
	// remove.
	KeepRemoteBranch bool
}

type EndResult struct {
	Stream  string            `json:"stream"`
	Applied bool              `json:"applied"`
	Members []EndMemberResult `json:"members"`
	// AgentPullRequests records what happened to every still-open pull
	// request that targeted a stream branch.
	AgentPullRequests []AgentPullRequestOutcome `json:"agent_pull_requests"`
	Errors            []string                  `json:"errors,omitempty"`
	// Forced names every finding `--force-unabsorbed` stepped over, and
	// ForcedReason the operator's recorded justification. Both are also
	// written to the event log, so the decision is auditable after the fact.
	Forced       []string `json:"forced,omitempty"`
	ForcedReason string   `json:"forced_reason,omitempty"`
}

type Engine struct {
	Store     *Store
	Git       Git
	GitHub    GitHub
	Worktrees WorktreeCreator
	// ProjectsRoot locates the canonical clones the preflight checks read.
	ProjectsRoot string
	// HooksCheck answers the readiness preflight's hooks question. Nil uses
	// the installed `wb hooks check`.
	HooksCheck HooksChecker
	// Login, Machine and Session identify the lease holder.
	Login   string
	Machine string
	Session string
	Now     func() time.Time
}

type Event struct {
	SchemaVersion int       `json:"schema_version"`
	Timestamp     time.Time `json:"timestamp"`
	Stream        string    `json:"stream"`
	Verb          string    `json:"verb"`
	// Phase is the step inside the verb — "preflight", "worktree",
	// "pull-request", "link", "unlink", "lease" — so a timeline can show
	// where a verb spent its time rather than only that it ran.
	Phase string `json:"phase,omitempty"`
	// Repository qualifies the event when it is about one member.
	Repository string `json:"repository,omitempty"`
	// Outcome is the envelope vocabulary: success, findings, refused.
	Outcome string `json:"outcome"`
	// RefusalCode is set only when Outcome is "refused". It is the stable
	// identifier a caller branches on.
	RefusalCode string `json:"refusal_code,omitempty"`
	// Detail is human-readable and redacted.
	Detail string `json:"detail,omitempty"`
	// DurationMS is the wall time of the phase, when the verb measured it.
	DurationMS int64 `json:"duration_ms,omitempty"`
	// Evidence carries the exact facts the verb relied on. Values are
	// redacted before the event is written.
	Evidence map[string]string `json:"evidence,omitempty"`

	// Provenance fields (wb#631, SDLC logging-gap analysis 2026-09-18): IDs
	// only, stamped by Append from the environment at zero cost, never a
	// prompt or response body. Additive and omitempty: a reader older than
	// this change simply never sees them, and EventSchemaVersion did not
	// need to move for a purely additive field.
	HarnessSessionID string `json:"harness_session_id,omitempty"`
	Harness          string `json:"harness,omitempty"`
	EffortLevel      string `json:"effort_level,omitempty"`
	AgentID          string `json:"agent_id,omitempty"`
	ToolUseID        string `json:"tool_use_id,omitempty"`
	WBVersion        string `json:"wb_version,omitempty"`
}

type EventAppender interface {
	Append(event Event) error
}

type ExecGit struct {
	// Timeout bounds each child. Zero uses defaultCommandTimeout.
	Timeout time.Duration
}

type ExecGitHub struct {
	Timeout time.Duration
}

type FileEventLog struct {
	Path string
	Now  func() time.Time
}

type Git interface {
	// CurrentBranch reports the checked-out branch of a worktree.
	CurrentBranch(ctx context.Context, dir string) (string, error)
	// DefaultBranch reports the repository's default branch from local
	// state. It must never contact the network.
	DefaultBranch(ctx context.Context, dir string) (string, error)
	// Fetch refreshes origin so a verb acts on a live view rather than a
	// session-start snapshot.
	Fetch(ctx context.Context, dir string) error
	// PushBranch publishes branch from dir and sets its upstream. It must
	// verify the pushed ref rather than trust the exit code.
	PushBranch(ctx context.Context, dir, branch string) (sha string, err error)
	// RemoteHead resolves origin/<branch>, reporting ok=false when the
	// branch does not exist on the remote.
	RemoteHead(ctx context.Context, dir, branch string) (sha string, ok bool, err error)
	// LocalHead resolves the worktree's HEAD.
	LocalHead(ctx context.Context, dir string) (string, error)
	// LocalBranchHead resolves a local branch without consulting origin. It is
	// used when a stream worktree has already disappeared: a surviving local
	// stream ref can still carry unpushed work that must block retirement.
	LocalBranchHead(ctx context.Context, dir, branch string) (sha string, ok bool, err error)
	// IsAncestor reports whether ancestor is reachable from descendant. Stream
	// cleanup uses commit ancestry, not patch similarity, when a merged PR is
	// the sole receipt that authorizes retiring a squash-merged member.
	IsAncestor(ctx context.Context, dir, ancestor, descendant string) (bool, error)
	// CommitsNotIn lists the commits on branch whose patch base does not
	// already carry, by patch identity rather than by SHA — a rebase landing
	// rewrites SHAs, so an ancestry test would refuse every landed stream
	// forever. Each commit carries its `git patch-id --stable`, which is what
	// clusters N branches carrying one body of work into one item.
	CommitsNotIn(ctx context.Context, dir, branch, base string) ([]Commit, error)
	// DirtyPaths lists modified or untracked paths in a worktree.
	DirtyPaths(ctx context.Context, dir string) ([]string, error)
	// Tags lists tags matching a glob pattern, newest version first.
	Tags(ctx context.Context, dir, pattern string) ([]string, error)
	// LogSubjects lists the subjects of commits in the exclusive range
	// from..to. An empty from means "every commit reachable from to".
	LogSubjects(ctx context.Context, dir, from, to string) ([]string, error)
	// DeleteRemoteBranch removes a branch from origin only if it remains at
	// expectedSHA, then verifies it is gone. The lease closes the interval
	// between stream proof and deletion: a later remote write must refuse, not
	// be erased as stream scaffolding.
	DeleteRemoteBranch(ctx context.Context, dir, branch, expectedSHA string) error
}

type GitHub interface {
	// CreateDraftPullRequest opens a draft pull request from head to base.
	CreateDraftPullRequest(ctx context.Context, dir, base, head, title, body string) (PullRequest, error)
	// UpdatePullRequestTitle changes one pull request's title and verifies the
	// remote effect before returning success.
	UpdatePullRequestTitle(ctx context.Context, dir string, number int, title string) error
	// PullRequestForBranch finds the open pull request whose head is branch.
	PullRequestForBranch(ctx context.Context, dir, branch string) (PullRequest, bool, error)
	// OpenPullRequestsTargeting lists every open pull request whose base is
	// base. `stream end` needs this to find the agent pull requests that
	// GitHub would silently retarget at `main` when the stream branch is
	// deleted.
	OpenPullRequestsTargeting(ctx context.Context, dir, base string) ([]PullRequest, error)
	// ClosePullRequest closes one pull request with a comment saying why.
	ClosePullRequest(ctx context.Context, dir string, number int, comment string) error
	// RetargetPullRequest moves one pull request onto a new base.
	RetargetPullRequest(ctx context.Context, dir string, number int, base string) error
	// PullRequest re-reads one pull request by number, reporting found=false
	// when it does not resolve. It is what makes a close or a retarget an
	// asserted effect rather than a trusted exit code.
	PullRequest(ctx context.Context, dir string, number int) (PullRequest, bool, error)
	// DefaultBranchStatus reports the conclusion of the most recent
	// completed CI run on the repository's default branch: "success",
	// "failure", or "" when it cannot be established.
	DefaultBranchStatus(ctx context.Context, dir, branch string) (conclusion string, err error)
}

type GoModule struct {
	// Path is the module path declared by the manifest.
	Path string `json:"path"`
	// Manifest is the worktree-relative go.mod path.
	Manifest string `json:"manifest"`
	// Directory is the worktree-relative module directory, which is what a
	// workspace `use` entry names. It is "." for a module at the root.
	Directory string `json:"directory"`
}

type HooksChecker func(path string) (findings []string, err error)

type Identity struct {
	Ecosystem Ecosystem `json:"ecosystem"`
	Name      string    `json:"name"`
	// Manifest is the worktree-relative path that declares the identity.
	Manifest string `json:"manifest"`
	// Directory is the worktree-relative directory of the manifest. For a Go
	// module it is the directory a workspace `use` entry names.
	Directory string `json:"directory"`
	// Workspace is the worktree-relative npm workspace that owns Manifest.
	// It is "." for packages in a repository-root workspace.
	Workspace string `json:"workspace,omitempty"`
}

type JoinOptions struct {
	Name       string
	Repository string
	Role       Role
	Base       string
}

type Lease struct {
	Login   string `json:"login,omitempty"`
	Machine string `json:"machine,omitempty"`
	Session string `json:"session,omitempty"`
	// RecordedHead is the stream head WB last observed on the remote. It is
	// what `wb stream sync` passes to `--force-with-lease`; it is empty
	// until a stream push records one.
	RecordedHead string    `json:"recorded_head,omitempty"`
	HeldSince    time.Time `json:"held_since"`
}

type Link struct {
	// Library is the library worktree the link points at. It may no longer
	// exist when the link is undone; that is deliberate.
	Library string `json:"library"`
	// LibraryRepository names the owning repository, which survives the
	// worktree being removed.
	LibraryRepository string    `json:"library_repository"`
	Mechanism         Mechanism `json:"mechanism"`
	State             LinkState `json:"state,omitempty"`
	// Identity is the published identity being replaced: a Go module path or
	// an npm package name.
	Identity string `json:"identity"`
	// PreviousVersion is the version the consumer declared before linking.
	// It is what `--undo` restores.
	PreviousVersion string `json:"previous_version,omitempty"`
	// ContentHash identifies the library working tree, including modified and
	// untracked files, that this link exposed. The library is uncommitted by
	// construction, so it has no SHA.
	ContentHash string `json:"content_hash,omitempty"`
	// Artifacts are the untracked paths the link created, relative to the
	// consumer worktree, so removal never guesses.
	Artifacts []string `json:"artifacts,omitempty"`
	// Workspace is the consumer-relative npm workspace containing the link.
	// Empty and "." both mean the repository root for backward compatibility.
	Workspace string    `json:"workspace,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type LinkState string

type LinkedConsumer struct {
	Repository      string    `json:"repository"`
	Worktree        string    `json:"worktree"`
	Library         string    `json:"library"`
	Mechanism       Mechanism `json:"mechanism"`
	Identity        string    `json:"identity"`
	PreviousVersion string    `json:"previous_version,omitempty"`
	ContentHash     string    `json:"content_hash,omitempty"`
}

type LinkedConsumerBinding struct {
	Repository string `json:"repository"`
	Worktree   string `json:"worktree"`
	Links      []Link `json:"links,omitempty"`
}

type Mechanism string

type Member struct {
	Repository string `json:"repository"`
	Role       Role   `json:"role"`
	// Worktree is the checkout `wb worktree create` published for this
	// member. It is the path every later verb acts in.
	Worktree string `json:"worktree"`
	// Canonical is the shared clone the worktree was cut from, recorded so
	// `status` can answer without re-deriving it from the projects root.
	Canonical string `json:"canonical"`
	Branch    string `json:"branch"`
	// Base is the branch the draft pull request targets.
	Base string `json:"base"`
	// PullRequest is the draft pull request opened from Branch to Base. Zero
	// means none was opened; PullRequestError then says why.
	PullRequest      int    `json:"pull_request,omitempty"`
	PullRequestURL   string `json:"pull_request_url,omitempty"`
	PullRequestError string `json:"pull_request_error,omitempty"`
	Lease            Lease  `json:"lease"`
	// Links are the live local links this member holds as a consumer. They
	// are written by `wb deps propagate local` and are the source of truth
	// for `--undo`, for `wb stream status`, and for the refusal that keeps a
	// linked worktree from being pushed or landed.
	Links    []Link    `json:"links,omitempty"`
	JoinedAt time.Time `json:"joined_at"`
}

type MemberLink struct {
	Member Member
	Link   Link
}

type MemberStatus struct {
	Repository     string `json:"repository"`
	Role           Role   `json:"role"`
	Worktree       string `json:"worktree"`
	Branch         string `json:"branch"`
	Base           string `json:"base"`
	PullRequest    int    `json:"pull_request,omitempty"`
	PullRequestURL string `json:"pull_request_url,omitempty"`
	// PullRequestMissing carries the reason no draft pull request exists.
	PullRequestMissing string `json:"pull_request_missing,omitempty"`
	// PullRequestRecovery is the exact WB verb that retries the missing
	// publication without asking an operator to hand-roll Git or GitHub calls.
	PullRequestRecovery string `json:"pull_request_recovery,omitempty"`
	// PullRequestBlocked explains when no safe automatic retry exists. A
	// divergent shared branch needs an owner decision; advertising join there
	// would only repeat the same refusal forever.
	PullRequestBlocked string `json:"pull_request_blocked,omitempty"`
	// PullRequestUnrecorded says GitHub has the member PR but stream.json does
	// not. Status remains read-only and join persists the discovered receipt.
	PullRequestUnrecorded bool `json:"pull_request_unrecorded,omitempty"`
	// LastPublicationError is persisted evidence from an earlier mutating
	// verb. It is separate from current discovery so status output cannot make
	// a historical push/create transcript look like work it just performed.
	LastPublicationError *PublicationFailure `json:"last_publication_error,omitempty"`
	// Unabsorbed is the number of commits on the stream branch that the base
	// does not carry by patch identity.
	Unabsorbed int `json:"unabsorbed"`
	// UnabsorbedClusters names each cluster of patch-identical work, so N
	// branches carrying one body of work read as one item rather than N. The
	// label is the commit subject; the IDENTITY is the patch id, so two
	// commits sharing a message are not collapsed and one change re-applied
	// with an edited message still is.
	UnabsorbedClusters []string `json:"unabsorbed_clusters,omitempty"`
	LeaseHolder        string   `json:"lease_holder,omitempty"`
	RecordedHead       string   `json:"recorded_head,omitempty"`
	LiveLinks          int      `json:"live_links"`
}

type MergedUntagged struct {
	Repository string   `json:"repository"`
	Base       string   `json:"base"`
	LatestTag  string   `json:"latest_tag,omitempty"`
	Commits    []string `json:"commits"`
}

type Phase string

type Preflight struct {
	Findings []PreflightFinding `json:"findings"`
}

type PreflightFinding struct {
	Repository string          `json:"repository"`
	Check      string          `json:"check"`
	Status     PreflightStatus `json:"status"`
	Detail     string          `json:"detail,omitempty"`
}

type PreflightInput struct {
	Repository string
	// Path is the checkout the checks read. It is the canonical clone at
	// start time: the stream worktrees do not exist yet, and refusing to
	// create them is the whole point of running these first.
	Path string
	// DefaultBranch is the branch the red-`main` check reads.
	DefaultBranch string
}

type PreflightStatus string

type PublicationFailure struct {
	Detail     string     `json:"detail"`
	OccurredAt *time.Time `json:"occurred_at,omitempty"`
}

type PullRequest struct {
	Number int    `json:"number"`
	URL    string `json:"url"`
	Title  string `json:"title"`
	Body   string `json:"body,omitempty"`
	Head   string `json:"head"`
	Base   string `json:"base"`
	Draft  bool   `json:"draft"`
	State  string `json:"state"`
	// HeadSHA and MergeSHA are immutable GitHub identities. They are required
	// when a stream member was already retired by wb pr land: the missing
	// checkout cannot be used as evidence of what the PR actually landed.
	HeadSHA  string `json:"head_sha,omitempty"`
	MergeSHA string `json:"merge_sha,omitempty"`
}

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

type Role string

type SquashAbsorptionReceipt struct {
	Target       string
	SourceBranch string
	SourceSHA    string
	CandidateSHA string
	LandingSHA   string
}

type StartOptions struct {
	Name string
	// Repositories are the members in declaration order. The first is the
	// library unless Library names another.
	Repositories []string
	Library      string
	// Base overrides the branch the draft pull requests target. Empty
	// resolves each repository's own default branch.
	Base string
}

type StartResult struct {
	Stream    Stream    `json:"stream"`
	Preflight Preflight `json:"preflight"`
	// Reported are the preflight findings that did not refuse the start but
	// that the operator must see. `stream-start-proves-the-fleet-is-ready`
	// allows a member to be reported instead of refused; nothing may be
	// silently passed.
	Reported []PreflightFinding `json:"reported,omitempty"`
	// TransitiveOmissions names consumers the dependency graph reaches that
	// the operator did not include. Leaving one out is legal; leaving one
	// out silently is not, because remote propagation bumps only members.
	TransitiveOmissions []string `json:"transitive_omissions,omitempty"`
}

type Status struct {
	Stream string `json:"stream"`
	Open   bool   `json:"open"`
	// Phase distinguishes a stream still being created from a usable one, so
	// an interrupted start is visible rather than looking like a healthy
	// stream with missing pull requests.
	Phase   Phase          `json:"phase"`
	Library string         `json:"library,omitempty"`
	Branch  string         `json:"branch"`
	Members []MemberStatus `json:"members"`
	// LinkedConsumers is gap one: consumers holding a live local link, and
	// the library worktree each is linked to.
	LinkedConsumers []LinkedConsumer `json:"linked_consumers"`
	// MergedUntagged is gap two: library changes that are merged into the
	// base but carry no tag yet.
	MergedUntagged *MergedUntagged `json:"merged_untagged,omitempty"`
	// ConsumersBehind is gap three: consumers still declaring a version
	// older than the library's newest published version.
	ConsumersBehind []ConsumerBehind `json:"consumers_behind"`
	// OpenAgentPullRequests are the pull requests targeting the stream
	// branch. They are the ones GitHub would silently retarget at the base
	// if the stream branch were deleted with them still open.
	OpenAgentPullRequests []AgentPullRequest `json:"open_agent_pull_requests"`
	// Unknowns record every question this report could not answer, so an
	// empty gap list never has to be read as "nothing is wrong".
	Unknowns []string `json:"unknowns,omitempty"`
}

type Store struct {
	// Root is <wb-home>/streams. Callers normally build a Store with Open.
	Root string
	// Now is the clock stream timestamps come from. Tests substitute it.
	Now func() time.Time
}

type Stream struct {
	SchemaVersion int       `json:"schema_version"`
	Name          string    `json:"name"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
	// Phase is the lifecycle position. An empty value reads as PhaseOpen so a
	// record written by an older binary stays usable.
	Phase Phase `json:"phase,omitempty"`
	// ArchivedFrom is set when a stream was archived to free its name for a
	// new stream. It records the name the record used to carry.
	ArchivedFrom string `json:"archived_from,omitempty"`
	// EndedAt is set by `wb stream end`. An ended stream is kept, not
	// deleted: its event log and link history are the evidence a later
	// report is built from, and `work-and-event-logs-are-never-pruned`
	// forbids discarding them as a side effect of ending the work.
	EndedAt *time.Time `json:"ended_at,omitempty"`
	Members []Member   `json:"members"`
	// LinkedConsumers are explicitly admitted alternate managed worktrees of a
	// repository already represented by Members. They participate only in
	// local dependency linking; stream branch, PR and repository ownership stay
	// with the member. Recording the exact checkout keeps undo and landing
	// guards authoritative without pretending the alternate branch is a member.
	LinkedConsumers []LinkedConsumerBinding `json:"linked_consumers,omitempty"`
}

type StreamLink struct {
	Stream     string `json:"stream"`
	Repository string `json:"repository"`
	Link       Link   `json:"link"`
}

type StreamLinkSource struct {
	Stream             string `json:"stream"`
	ConsumerRepository string `json:"consumer_repository"`
	// ConsumerWorktree is the linked consumer's worktree path, so a refusal
	// can name the exact repoint command without a second lookup.
	ConsumerWorktree string `json:"consumer_worktree"`
	Link             Link   `json:"link"`
}

type Unreadable struct {
	Name   string `json:"name"`
	Path   string `json:"path"`
	Reason string `json:"reason"`
}

type WorktreeCreator interface {
	// PlannedWorktree is where Create will publish one repository's checkout.
	// It performs no side effect, so the stream record can carry each
	// member's intended coordinates BEFORE anything is created — which is
	// what makes an interrupted start recoverable.
	PlannedWorktree(task, repository string) (string, error)
	Create(ctx context.Context, task, branch string, repositories []string) ([]CreatedWorktree, error)
	// Remove retires one member's worktree through the existing cleanup
	// path. `stream end` delegates removal rather than deleting directories.
	Remove(ctx context.Context, task, repository, worktree string, receipt *SquashAbsorptionReceipt) error
}