forge

type Authenticator interface {
	// Login runs the provider's interactive authentication flow, surfacing any
	// user-facing step through p, and returns a usable API token on success. It
	// blocks until the user completes the flow, ctx is cancelled, or the flow's own
	// deadline (e.g. the device-code expiry) elapses.
	//
	// Returns [ErrNotSupported] when interactive login is unavailable in the
	// provider's current configuration; the caller then falls back to manual entry.
	Login(ctx context.Context, p Prompter) (token string, err error)
}

type ChecksumProvider interface {
	// DownloadChecksumManifest returns the raw bytes of the checksums
	// manifest for the given release.
	//
	// The implementation MUST enforce maxBytes and return an error when the
	// response exceeds it, so a hostile server cannot stream indefinitely.
	// Enforcement belongs here, at the trust boundary, not in the caller: a
	// provider reaching a URL of its own composition is the only code that
	// sees the response before it is buffered. [DefaultMaxChecksumsSize] is
	// a reasonable bound, but the CALLER chooses the value and passes it —
	// tools shipping unusually large artefacts legitimately raise it.
	//
	// Returns [ErrNotSupported] when the provider is configured in a
	// way that disables checksum retrieval (e.g. the Direct
	// provider's `checksum_url_template` param is empty). The caller
	// treats [ErrNotSupported] exactly like "provider does not
	// implement this interface" — fall back to asset-by-name lookup
	// if one is available, otherwise respect the require_checksum
	// policy.
	DownloadChecksumManifest(ctx context.Context, rel Release, maxBytes int64) ([]byte, error)
}

type Comment struct {
	ID        int64
	Author    string
	Body      string
	CreatedAt time.Time
	UpdatedAt time.Time

	// System reports a comment the FORGE generated — a label change, a state
	// transition, an assignment — rather than one a person wrote.
	//
	// A caller relaying comments to an audience outside the tracker must skip
	// these, or it republishes triage mechanics as though they were answers.
	System bool
}

type CommentDraft struct {
	// Body is the comment text, in the forge's markdown flavour. REQUIRED.
	Body string

	// IdempotencyKey makes posting at-most-once across a retry. Empty opts out.
	//
	// When it is non-empty the provider MUST look for an existing comment
	// carrying the key before posting, and MUST return that comment rather than
	// posting a second. The key is written into the comment so the search can
	// find it, using [AppendIdempotencyKey] — the same visible marker
	// [IssueFiler] uses, for the reason recorded there: an HTML comment is
	// hidden on three of the four forges and renders as literal text on
	// Bitbucket.
	//
	// # The limits, stated rather than discovered
	//
	//   - It is NOT atomic. Two concurrent posts with the same key can both
	//     find nothing and both post. This defends against a RETRY, not against
	//     concurrent callers.
	//   - The key is published, because it lives in a readable comment body.
	//   - It costs a full listing of the target's comments, not one filtered
	//     request. No forge offers a server-side search over comments — checked
	//     at the pinned client versions — so the provider pages through them and
	//     matches locally. On a busy pull request that is several requests.
	//
	// A provider confirms the marker is actually present rather than trusting a
	// fuzzy match, exactly as [IssueFiler.CreateIssue] does: a near-miss
	// returning someone else's comment is worse than posting a duplicate.
	IdempotencyKey string

	// Unsanitised sends Body verbatim, skipping the secret redaction otherwise
	// applied. A comment reaches the same audience an issue does, so it gets
	// the same defence by default.
	Unsanitised bool
}

type CommentQuery struct {
	// Since limits comments to those created at or after this time. Zero means
	// all comments.
	//
	// Providers whose forge supports it filter server-side. Those whose forge
	// does not — GitLab has no such parameter — request newest-first and stop
	// as soon as they pass Since, so a caller still pays only for what it asked
	// for.
	//
	// Because those two routes produce opposite orders, NO ORDER IS PROMISED.
	// Forcing one to match the other would mean buffering the whole set, which
	// is what Since exists to avoid. Sort what you collect if order matters.
	Since time.Time

	// PageSize hints at the provider's internal page size.
	PageSize int
}

type Config interface {
	GetString(key string) string
	Sub(key string) Config
}

type Contents interface {
	// GetFile returns the bytes of path in owner/repo at ref.
	//
	// ref is REQUIRED. A read at "whatever the default branch is right now" is
	// not reproducible, and a caller recording provenance needs to know what it
	// read.
	//
	// Returns ErrNotFound when the file does not exist at that ref — which is an
	// ordinary answer to "does this repository carry X?", not a failure. A
	// permission error is NOT ErrNotFound: a caller must never be told a file is
	// absent because its token was too weak.
	//
	// The implementation MUST enforce maxBytes. Enforcement belongs here, at the
	// trust boundary, for the same reason it does on [ChecksumProvider]: the
	// provider is the only code that sees the response before it is buffered.
	// Where the underlying SDK exposes a reader, use io.LimitedReader; where it
	// buffers internally, check the size the API reports BEFORE fetching and
	// re-check the length after. [DefaultMaxFileSize] is a reasonable bound, but
	// the CALLER chooses the value and passes it.
	GetFile(ctx context.Context, owner, repo, path, ref string, maxBytes int64) ([]byte, error)
}

type CredentialSource func(ctx context.Context) (string, error)

type DeviceCode struct {
	// UserCode is the short code the user types at VerificationURI.
	UserCode string
	// VerificationURI is where the user enters UserCode to authorize the request.
	VerificationURI string
	// VerificationURIComplete, when non-empty, is a URL that pre-fills the code
	// (some providers supply it so the user need not type UserCode).
	VerificationURIComplete string
	// ExpiresIn is how long UserCode remains valid.
	ExpiresIn time.Duration
}

type DraftPublisher interface {
	// PublishRelease publishes the release on tagName, making it visible to
	// everyone.
	//
	// # It is SAFE to call when nothing was stranded
	//
	// A release that is already published is returned with a NIL ERROR. Not
	// [ErrAlreadyExists]: the caller asked for a published release on that tag
	// and there is one.
	//
	// This is the guarantee a re-running release tool depends on. A verb whose
	// whole purpose is recovering from an interrupted run has to be safe to
	// call when the run was not, in fact, interrupted — otherwise every caller
	// writes the same errors.Is dance and half of them get it wrong.
	//
	// Both platforms make it free. Measured on 2026-09-07: a publish of an
	// already-published release answers 200 on GitHub and on Gitea 1.27.3, with
	// published_at UNCHANGED, so a repeat does not re-date the release.
	//
	// # A tag carrying MORE THAN ONE release is refused
	//
	// GitHub permits several releases on one tag — a spike created three — so a
	// provider can find more than one candidate, and it MUST NOT PICK.
	//
	// It returns a plain error naming every candidate, and publishes nothing.
	// Deliberately not a sentinel: there is nothing a caller can do
	// programmatically, because choosing which of two drafts is the real
	// release is a judgement about intent and this contract has no verb to
	// remove the other. Naming them is the whole of the help available, and
	// guessing would publish the wrong release under a tag people trust with no
	// delete to undo it.
	//
	// A conformant provider can no longer CREATE that state, but repositories
	// carry it today, and those are exactly the ones this verb is for.
	//
	// # Returns
	//
	// The published release, and one of:
	//
	//   - nil, when it is now published — whether this call published it or it
	//     already was.
	//   - an error wrapping [ErrNotFound] when the tag carries NO RELEASE AT
	//     ALL. That is not the same as a stranded draft, and a caller that
	//     confuses them will create a release it meant to finish.
	//
	//     It means only that, which is why a provider must not reach for it
	//     when a write was accepted and answered with nothing: the release
	//     exists at that point and has probably just been published, and a
	//     caller branching as this sentence instructs would create a duplicate.
	//     A plain error is the honest answer there.
	//
	//     On a forge where a draft is only visible to a caller with write
	//     access, ErrNotFound also covers "your token cannot see it". GitHub is
	//     one: drafts appear in the release listing for a writer and nowhere
	//     else, so a read-scoped token is told a draft it cannot see is absent.
	//   - a plain error when the tag carries more than one release, or a
	//     refusal sentinel. Nothing was published.
	//
	// # What it does NOT do
	//
	// It does not attach anything. A caller wanting to be sure the assets are
	// complete enumerates them with [Release.GetAssets] first; publishing what
	// is there is the whole of this verb.
	//
	// It does not un-publish, and there is no discard. Destroying published
	// things is a maintainer act in this estate rather than a library call,
	// which is why [ReleasePublisher] carries no delete and [PullRequests]
	// carries no Merge. A provider's internal discard of a draft it created
	// moments earlier remains unreachable from here.
	PublishRelease(ctx context.Context, owner, repo, tagName string) (Release, error)
}

type Endpoint struct {
	// Type selects the provider implementation — the string it registered under.
	Type string

	// Host selects the instance. Empty means the provider's own default, which
	// for a hosted forge is its public one and for a provider with no notion of
	// a host is simply unused.
	Host string

	// Name selects which configured source of that type this is, and scopes the
	// configuration subtree the provider reads. Empty means the default source,
	// reading the bare <type> subtree.
	//
	// It exists because Type and Host together do not always identify a
	// connection. Two credentials for one host are two sources; so are two
	// download sources of a provider that never looks at Host at all.
	//
	// It must not contain a dot. The subtree is composed as <type>.<name>, and a
	// dotted name would nest a level deeper than intended in configuration
	// backends that treat dots as path separators — silently reading a subtree
	// nobody meant.
	Name string
}

type GitRemote struct {
	// CloneURL is the URL to clone from, as reported by the API.
	//
	// It is DATA from the forge, not a constant, so a caller attaching a
	// credential to it must pin it first with [HostTrusted] — the same rule that
	// governs release asset URLs.
	CloneURL string

	// DefaultBranch is the branch a clone lands on, and the natural ref to pass
	// to [Contents.GetFile].
	DefaultBranch string
}

type Issue struct {
	// Number is the PER-PROJECT issue number — GitLab's iid, GitHub's number,
	// Gitea's index. It is not the forge's global ID, because the global ID is
	// not what a URL or a human uses, and it is the number a caller polls with.
	Number int

	Title  string
	Body   string
	State  IssueState
	Labels []string

	// URL is the human-facing web URL, and for many callers the single most
	// important field: it is what gets shown to the person the issue was filed
	// for.
	URL string

	Author    string
	CreatedAt time.Time
	UpdatedAt time.Time

	// ClosedAt is zero while the issue is open.
	ClosedAt time.Time

	// ClosedBy is empty when the forge does not report it.
	ClosedBy string
}

type IssueCommenter interface {
	// CreateIssueComment posts a comment on the issue numbered number.
	//
	// Returns an error wrapping [ErrNotFound] when no such issue exists. A
	// permission refusal is NOT ErrNotFound: a caller must never be told an
	// issue is absent because its token was too weak.
	//
	// When draft.IdempotencyKey is set and a comment already carries it, the
	// EXISTING comment is returned and nothing is posted. See
	// [CommentDraft.IdempotencyKey] for what that guarantee does and does not
	// cover.
	//
	// # The order is load-bearing
	//
	// Body is sanitised with [Sanitise] unless draft.Unsanitised is set, and the
	// key is appended AFTER that with [AppendIdempotencyKey] — the same order
	// [IssueFiler.CreateIssue] requires, for the same reason. Sanitising
	// afterwards feeds the key to the redactor, which rewrites a long opaque
	// string, and the next search then looks for a key that was never written.
	// Every retry posts a duplicate, silently.
	CreateIssueComment(
		ctx context.Context, owner, repo string, number int, draft CommentDraft,
	) (Comment, error)
}

type IssueDraft struct {
	Title string
	Body  string

	// Labels are the label NAMES to attach, and EVERY ONE MUST ALREADY EXIST
	// on the repository. A name that matches no label is not sent and is
	// reported back — see [IssueFiler.CreateIssue].
	//
	// The rule is the same one [PullRequestDraft.Labels] states, deliberately:
	// a caller learning it once should not find it means something else on the
	// neighbouring type in this package.
	//
	// Matching is EXACT, so "Support" does not resolve to a "support" label.
	// A case-insensitive match is the failure that is silently wrong rather
	// than loudly wrong — it binds a caller's name onto a label somebody else
	// wrote, files against it, and reports success.
	//
	// Setting a label NEVER CREATES ONE, even on the forges that would. GitLab
	// and GitHub both create an unknown name on the spot; Gitea cannot, because
	// its API takes label IDs. The contract declines rather than guaranteeing
	// what one adapter provably cannot honour — and because this is the
	// capability that files a report into a project THE CALLER MAY NOT OWN, so
	// creating a label as a side effect turns a typo into a permanent artefact
	// on somebody else's tracker.
	//
	// Empty or nil attaches nothing.
	//
	// Specified by spec 0017:
	// https://gitlab.com/phpboyscout/go/forge/-/wikis/specs/0017-one-rule-for-labels
	Labels []string

	// IdempotencyKey makes filing at-most-once across a retry. Empty opts out,
	// and a create is then a plain create.
	//
	// It is PUBLISHED: the provider writes it into the issue body, where anyone
	// who can read the issue can read it. Use an opaque value derived for this
	// purpose — never a session token, a user identifier, or anything else
	// whose disclosure would matter.
	IdempotencyKey string

	// Unsanitised sends Title and Body verbatim, skipping the secret redaction
	// and mention neutralisation [IssueFiler.CreateIssue] applies by default.
	//
	// Named to be uncomfortable, because it should be. The default exists
	// because both failures it prevents are irreversible and land on someone
	// who is not the caller.
	//
	// The legitimate use is content the caller has already sanitised under a
	// policy of its own, or content where the default's false positives — most
	// often a SHA-256 digest — would corrupt the report.
	Unsanitised bool
}

type IssueFiler interface {
	// CreateIssue files an issue and returns it as the forge recorded it —
	// including the Number and URL, which a caller needs to link a human to it
	// and to poll it later.
	//
	// # Sanitisation
	//
	// Title and Body are passed through [Sanitise] before sending, unless
	// draft.Unsanitised is set. See that function for what it removes and why
	// it is safe to apply by default.
	//
	// # At-most-once
	//
	// When draft.IdempotencyKey is non-empty, the provider MUST look for an
	// existing issue carrying that key before creating one, and MUST return
	// the existing issue rather than filing a second. The key is written into
	// the created issue so the search can find it.
	//
	// The guarantee has limits, and they are stated here rather than
	// discovered:
	//
	//   - It is NOT atomic. Two concurrent creates with the same key can both
	//     find nothing and both file. This defends against a RETRY, not
	//     against concurrent callers.
	//   - The key is published, because it lives in a readable issue body.
	//   - It costs one extra search per create.
	//
	// The key is appended AFTER sanitisation. Sanitising afterwards would feed
	// the key to the redactor, and a long opaque key would be rewritten —
	// silently breaking the guarantee, because the search would then look for a
	// key the issue does not carry.
	//
	// # Read this before writing the usual error check
	//
	// When draft.Labels is set and some label could not be applied, CreateIssue
	// returns the FILED ISSUE together with an error wrapping [ErrNotHonoured].
	// So the reflexive idiom
	//
	//	issue, err := f.CreateIssue(ctx, owner, repo, draft)
	//	if err != nil {
	//	    return err
	//	}
	//
	// treats a filed report as a failure. The idiom that is correct:
	//
	//	issue, err := f.CreateIssue(ctx, owner, repo, draft)
	//	if err != nil && !errors.Is(err, forge.ErrNotHonoured) {
	//	    return err // a real failure; nothing was filed
	//	}
	//	// issue exists either way. Log err if non-nil: a label was dropped.
	//
	// A caller that sets no labels can never see this, and its error handling
	// does not change.
	//
	// Getting it wrong is less costly here than elsewhere, and only because of
	// the at-most-once guarantee above: a caller that retries on the sentinel
	// finds the existing issue rather than filing a duplicate — PROVIDED it set
	// an IdempotencyKey. Without one, the retry files a second report.
	//
	// # Why a dropped label is reported rather than refused
	//
	// A report exists to be filed. Losing it over a marker is the worse
	// outcome, and the marker is the decoration — so the issue is created and
	// the loss is named, never the reverse.
	//
	// A name that matches no label is caught by resolving draft.Labels against
	// the repository's labels before sending. That listing MUST be paginated:
	// GitLab's default page is 20, GitHub pages by the Link header, and Gitea
	// keeps repository and organisation labels on SEPARATE endpoints where the
	// repository listing does not include the organisation's. Resolving against
	// a truncated set reports a label absent that the caller can see in the UI.
	//
	// The hint on the returned error names the labels that did not land,
	// reachable with errors.Hints.
	CreateIssue(ctx context.Context, owner, repo string, draft IssueDraft) (Issue, error)
}

type IssueQuery struct {
	// Text matches against title and body. Empty matches everything.
	//
	// This is a FILTER, not a relevance ranking. Providers use server-side
	// search where the forge offers it and filter client-side where it does
	// not, so match quality differs between providers and no ordering is
	// promised.
	//
	// A provider MUST NOT ignore this field and return everything. A caller
	// checking the first results for a duplicate and finding none would
	// conclude there are none — the false negative that files a duplicate into
	// a public tracker.
	//
	// Judging whether a match is a CREDIBLE duplicate remains the caller's.
	Text string

	// State narrows to open or closed issues. IssueStateUnknown means both.
	State IssueState

	// Labels narrows to issues carrying ALL of these.
	Labels []string

	// PageSize hints at the provider's internal page size. Zero means the
	// provider's default.
	PageSize int
}

type IssueState string

type Issues interface {
	// SearchIssues yields issues matching q, calling yield once per issue.
	// Returning false from yield stops the search early and is not an error.
	//
	// The returned error is the single, complete answer to "did I see
	// everything?". A nil error means the search completed; a NON-NIL error
	// means the caller holds a PARTIAL view.
	//
	// That distinction is sharper here than anywhere else in this module. A
	// duplicate search that fails and is read as "no duplicates found" causes a
	// caller to file a duplicate into a public tracker — so an empty result set
	// and a failed search must never be the same answer.
	SearchIssues(ctx context.Context, owner, repo string, q IssueQuery, yield func(Issue) bool) error

	// GetIssue returns one issue by its per-project number.
	//
	// Returns ErrNotFound when no such issue exists. A permission refusal is
	// NOT ErrNotFound: a caller must never be told an issue is absent because
	// its token was too weak.
	GetIssue(ctx context.Context, owner, repo string, number int) (Issue, error)

	// ListComments yields an issue's comments, calling yield once per comment.
	// Returning false from yield stops early and is not an error. The error
	// carries the same meaning as SearchIssues'.
	//
	// System comments are included and flagged; filtering them is the caller's
	// decision, because "what counts as noise" is a policy this contract has no
	// business fixing.
	ListComments(ctx context.Context, owner, repo string, number int, q CommentQuery, yield func(Comment) bool) error
}

type KeyManager interface {
	// UploadKey registers publicKey — an OpenSSH-format public key ("ssh-ed25519
	// AAAA… comment") — under the given human-readable name on the authenticated
	// account. The provider resolves its own credentials (as for the release
	// [Provider]); name is a label the user will see in the account's key list.
	UploadKey(ctx context.Context, name string, publicKey []byte) error
}

type MergeRequest = PullRequest

type MergeRequestCommenter = PullRequestCommenter

type MergeRequestDraft = PullRequestDraft

type MergeRequestState = PullRequestState

type MergeRequests = PullRequests

type Option func(*Options)

type Options struct {
	// Logger receives this provider's diagnostics. Never nil after
	// [NewOptions]: an unset logger becomes one that discards.
	Logger *slog.Logger

	// HTTPTransport is the transport a provider should build its clients on, so
	// several providers share one connection pool. Nil means the provider builds
	// its own, which is the default and always valid.
	//
	// A provider using it still builds its own client, and so keeps its own
	// redirect and sensitive-header policy. See [WithHTTPTransport].
	HTTPTransport http.RoundTripper

	// HTTPClient is a fully built client a provider should use as-is, replacing
	// the one it would have built — redirect policy included. Nil means the
	// provider builds its own.
	//
	// A provider that honours both prefers this one, because a caller supplying
	// a whole client has asked for exactly that. See [WithHTTPClient] for what it
	// transfers.
	HTTPClient *http.Client
}

type Prompter interface {
	// ShowDeviceCode presents a device-authorization prompt to the user — typically
	// "open dc.VerificationURI and enter dc.UserCode". It returns once the prompt has
	// been shown; the [Authenticator] then polls the provider for completion. A
	// non-nil error aborts the login.
	ShowDeviceCode(ctx context.Context, dc DeviceCode) error
}

type Provider interface {
	GetLatestRelease(ctx context.Context, owner, repo string) (Release, error)
	GetReleaseByTag(ctx context.Context, owner, repo, tag string) (Release, error)

	// ListReleases returns up to limit releases, newest first.
	//
	// # Pagination contract
	//
	// limit is a total, not a page size. A provider MUST paginate across the
	// platform's pages until it has gathered limit releases or the history is
	// exhausted, whichever comes first — the caller receives "everything up to
	// limit", never a silently truncated first page. This matters because
	// callers request a fixed window (GTB's changelog walk asks for 100) that
	// commonly exceeds a platform's per-page maximum: GitHub and GitLab cap
	// per_page at 100, and Gitea instances commonly cap page size at 50, so a
	// single request would drop older releases and yield a truncated changelog.
	//
	// A limit <= 0 means "no explicit bound"; a provider returns its natural
	// first page rather than walking all history.
	//
	// A provider whose platform has no concept of enumerable releases returns an
	// error wrapping [ErrNotSupported] (Bitbucket Downloads does this).
	//
	// # Rate limiting
	//
	// forge does not retry internally. A provider surfaces the platform's
	// rate-limit response (HTTP 429, or GitHub's 403 + X-RateLimit-Remaining: 0)
	// as an error, wrapped verbatim so a caller can inspect it for a Retry-After
	// and decide whether to back off — pagination loops here do not sleep and
	// retry on the caller's behalf.
	ListReleases(ctx context.Context, owner, repo string, limit int) ([]Release, error)

	// DownloadReleaseAsset opens a stream of the asset's bytes.
	//
	// The second return value is a REDIRECT URL, and it is a security
	// boundary rather than a convenience. Some APIs answer an asset request
	// with a redirect to storage the client is expected to follow itself
	// (this is go-github's behaviour, which surfaces the location instead of
	// following it). A provider that receives such a redirect and does NOT
	// follow it returns the location here, with a nil or empty reader.
	//
	// Callers are expected to REFUSE a non-empty redirect rather than follow
	// it: following one would fetch bytes from a host the caller never
	// vetted, defeating the point of pinning the API host. Return "" whenever
	// the body is served directly, which is the common case — three of the
	// four first-party providers always do.
	//
	// A provider MAY instead resolve the redirect itself, provided it follows
	// it with a CREDENTIAL-FREE HTTP client and returns the resulting body with
	// "" for the redirect URL. This is the GitHub adapter's stance: go-github
	// follows the storage redirect using a token-free client, so no credential
	// reaches the redirect target and the caller's refuse-on-redirect boundary
	// is satisfied by construction (the URL is always ""). A provider that
	// takes this route MUST NOT attach its API credential to the followed
	// request — the pin exists precisely because the redirect target is
	// author-influenced and unvetted.
	DownloadReleaseAsset(ctx context.Context, owner, repo string, asset ReleaseAsset) (io.ReadCloser, string, error)
}

type ProviderFactory func(
	ctx context.Context,
	ep Endpoint,
	cfg Config,
	opts ...Option,
) (Provider, error)

type ProviderUnwrapper interface {
	Unwrap() Provider
}

type PullRequest struct {
	// Number is the PER-PROJECT number — GitLab's iid, GitHub's number,
	// Gitea's index. It is not the forge's global ID, because the global ID is
	// not what a URL or a human uses, and it is the number the other methods
	// here take.
	Number int

	Title string
	Body  string
	State PullRequestState

	SourceBranch string
	TargetBranch string

	// URL is the human-facing web URL.
	URL string

	Author    string
	CreatedAt time.Time
	UpdatedAt time.Time

	// MergedAt is zero unless State is PullRequestStateMerged.
	//
	// It is the ordering key for [PullRequests.FindLastMerged], and it is not
	// interchangeable with UpdatedAt: a comment posted after a merge moves
	// UpdatedAt and leaves this alone.
	MergedAt time.Time

	// ClosedAt is zero while the pull request is open.
	ClosedAt time.Time

	// Labels are the label NAMES the pull request carries, as the forge
	// reported them.
	//
	// Empty means the pull request carries none, OR that the forge has no
	// label concept — Bitbucket Cloud does not. The two are not distinguished
	// here, because a caller that must know asks the provider matrix rather
	// than inferring a platform's feature set from one empty slice.
	Labels []string
}

type PullRequestCommenter interface {
	// Comment posts a comment on the pull request numbered number.
	//
	// Returns an error wrapping [ErrNotFound] when no such pull request exists,
	// and honours draft.IdempotencyKey as [IssueCommenter.CreateIssueComment]
	// does — including the sanitise-then-append order, which is load-bearing.
	//
	// # This is a conversation comment, not a review comment
	//
	// A provider MUST post to the pull request's conversation rather than to a
	// diff. On GitHub the two are different endpoints whose names invite the
	// mistake: IssuesService.CreateComment is this one, because a pull request
	// IS an issue there, while PullRequestsService.CreateComment posts a review
	// comment against a line of a diff. Both compile, both succeed, and only one
	// is what a caller asked for.
	Comment(
		ctx context.Context, owner, repo string, number int, draft CommentDraft,
	) (Comment, error)

	// ListRequestComments returns every comment on the pull request numbered
	// number.
	//
	// # Why the name is neither ListComments nor ListPullRequestComments
	//
	// ListComments is TAKEN. [Issues.ListComments] already has it, with a yield
	// signature, and every provider implements Issues and this on one concrete
	// type — so reusing the name makes this interface unimplementable by
	// everybody. Go refuses two methods of one name on one type, which is the
	// loud version of the collision this file's opening comment describes.
	//
	// ListPullRequestComments would collide with nothing and would hand the
	// GitLab-flavoured noun back through [MergeRequestCommenter], which is the
	// thing [PullRequests]' bare Find, Create and Close exist to avoid.
	//
	// "Request" is the half both names share, so this reads correctly under
	// either.
	//
	// # It exists so at-most-once can be CHECKED
	//
	// [Issues.ListComments] covers the issue side and nothing covered this one,
	// which would have made draft.IdempotencyKey a guarantee the contract
	// asserts, providers implement privately, and the conformance harness cannot
	// test. A check that cannot fail is worse than no check.
	//
	// # It MUST return the complete set
	//
	// It paginates internally. A NON-NIL error means the slice is PARTIAL and
	// must not be read as the full set — the rule [Issues.ListComments] states
	// and which bites harder here, because a partial view read as "no duplicate"
	// is what posts the duplicate.
	ListRequestComments(ctx context.Context, owner, repo string, number int) ([]Comment, error)
}

type PullRequestDraft struct {
	Title string
	Body  string

	// SourceBranch holds the proposed commits. It must already exist on the
	// forge; this contract does not create branches.
	SourceBranch string

	// TargetBranch is what the change is proposed against. Empty means the
	// repository's default branch.
	TargetBranch string

	// Labels are the label NAMES to attach, and EVERY ONE MUST ALREADY EXIST
	// on the repository. A name that matches no label is not sent and is
	// reported back — see [PullRequests.Create].
	//
	// Names, not identifiers: it is what a human types into the forge's filter
	// box, it is what [IssueDraft.Labels] already takes, and it is the only
	// identifier that means the same thing on every forge. Matching is EXACT,
	// so "Release::Pending" does not resolve to a "release::pending" label.
	//
	// Setting a label NEVER CREATES ONE, even on the forges that would. GitLab
	// and GitHub both create an unknown name on the spot; Gitea cannot, because
	// its API takes label IDs and an unresolvable name has no ID to send. The
	// contract declines rather than guaranteeing what one adapter cannot
	// honour, and because creating a label as a side effect of tagging a pull
	// request turns a caller's typo into a permanent artefact on someone's
	// project.
	//
	// Empty or nil attaches nothing. There is no way to change a pull request's
	// labels afterwards; see the file comment.
	//
	// Specified by spec 0014 D2 and D7:
	// https://gitlab.com/phpboyscout/go/forge/-/wikis/specs/0014-labels-on-pull-requests
	Labels []string
}

type PullRequestState string

type PullRequests interface {
	// Find returns the OPEN pull request opened from sourceBranch.
	//
	// At most one can exist: a forge refuses a second open request for the same
	// source and target pair. Verified across 50 open merge requests sampled
	// group-wide, no source/target pair carried two.
	//
	// Returns an error wrapping ErrNotFound when there is none. A permission
	// refusal is NOT ErrNotFound: a caller must never be told nothing is open
	// because its token was too weak, since the response to that is to open a
	// duplicate.
	Find(ctx context.Context, owner, repo, sourceBranch string) (PullRequest, error)

	// FindLastMerged returns the most recently MERGED pull request from
	// sourceBranch, ordered by merge time.
	//
	// It is separate from Find because the two differ in CARDINALITY, not
	// merely in which state they look at. A release branch is reused: one such
	// branch carried 0 open and 53 merged merge requests. At most one can be
	// open; many have merged, so this one needs an ordering and Find does not.
	// A single method taking a state would return "the one" in one mode and an
	// arbitrary one of fifty-three in the other, with a signature unable to say
	// which.
	//
	// Ordering is by MERGE time. A provider must not order by last-updated,
	// which drifts after the merge and is a claim about recency rather than
	// evidence of it.
	//
	// Returns an error wrapping ErrNotFound when nothing from that branch has
	// merged.
	FindLastMerged(ctx context.Context, owner, repo, sourceBranch string) (PullRequest, error)

	// Create opens a pull request and returns it as the forge recorded it,
	// including the Number and URL.
	//
	// It is NOT idempotent and makes no at-most-once claim. A caller that must
	// not duplicate calls Find first, and accepts that the gap between the two
	// is a race it owns.
	//
	// # Read this before writing the usual error check
	//
	// When draft.Labels is set and some label could not be applied, Create
	// returns the CREATED PULL REQUEST together with an error wrapping
	// [ErrNotHonoured]. So the reflexive idiom
	//
	//	pr, err := p.Create(ctx, owner, repo, draft)
	//	if err != nil {
	//	    return err
	//	}
	//
	// treats a successful create as a failure. Because Create makes no
	// at-most-once claim, the retry that usually follows opens a SECOND pull
	// request. The idiom that is correct:
	//
	//	pr, err := p.Create(ctx, owner, repo, draft)
	//	if err != nil && !errors.Is(err, forge.ErrNotHonoured) {
	//	    return err // a real failure; nothing was created
	//	}
	//	// pr exists either way. Log err if non-nil: a label was dropped.
	//
	// A caller that sets no labels can never see this, and its error handling
	// does not change.
	//
	// # What "could not be applied" covers
	//
	// A provider establishes what was applied by READING THE RESULT BACK and
	// comparing it against draft.Labels, never by assuming the request worked.
	// Two things are caught only that way:
	//
	//   - A name that resolved and did not stick. GitLab's scoped labels are
	//     mutually exclusive, so a draft carrying both "release::pending" and
	//     "release::tagged" keeps one and the forge says nothing.
	//   - Anything else a forge drops silently.
	//
	// A name that matches no existing label is caught earlier, by resolving
	// draft.Labels against the repository's labels before sending. That listing
	// MUST be paginated: GitLab's default page is 20, and resolving against a
	// truncated set reports a label absent that the caller can see in the UI.
	//
	// Either way the hint on the returned error names the labels that did not
	// land, reachable with errors.Hints.
	//
	// A provider whose forge has no labels at all creates the pull request and
	// reports every requested label as not honoured. It does not refuse: a
	// caller must not lose a pull request over a marker.
	Create(ctx context.Context, owner, repo string, draft PullRequestDraft) (PullRequest, error)

	// Update replaces the title and body. Both are sent as given.
	//
	// There is no partial update and no way to clear a field, because every
	// call supplies the whole value. The alternative had a trap in it: a
	// forge distinguishes "field omitted, leave it" from "field sent empty,
	// clear it", and a plain string cannot express both — read as "leave" and
	// a caller can never clear, read as "clear" and a caller changing only the
	// title silently wipes the body.
	//
	// Supplying both costs nothing, since Find already returned them.
	//
	// # The lost-update race is real and is not solved here
	//
	// A human editing the body between a caller's read and this write loses
	// that edit. No first-party forge offers a compare-and-swap on this
	// operation, so the race exists under any signature. Which regions of a
	// body are machine-owned is the CALLER's policy, stated once in its own
	// composition — this contract does not merge, diff or protect regions.
	Update(ctx context.Context, owner, repo string, number int, title, body string) error

	// Close closes a pull request without merging it.
	//
	// Returns an error wrapping ErrNotFound when no such pull request exists,
	// so a caller cleaning up can treat "already gone" as success. Closing an
	// already-closed pull request is not an error.
	Close(ctx context.Context, owner, repo string, number int) error

	// ResolveMergedCommit returns the commit ON THE TARGET BRANCH that this
	// pull request produced.
	//
	// This is the method the whole capability exists for.
	//
	// # The returned SHA has been confirmed present on the target branch
	//
	// That confirmation is the contract. HOW a provider finds its candidate is
	// its own business — the forge's recorded merge commit, its squash commit,
	// a reverse lookup from the branch's recent history — but it MUST NOT
	// return one it has not checked.
	//
	// # Confirmation means containment, not existence
	//
	// An orphaned commit still EXISTS. Fetching it succeeds and returns its
	// message intact, so a provider that confirms by fetching passes its own
	// check and is still wrong. Only asking which branches contain the commit
	// separates the two. On the reproduced case that query returned no branches
	// for the orphan and the target branch for the commit that landed.
	//
	// # Returns ErrNotFound when nothing confirms
	//
	// Never a best guess. "I could not establish what landed" and "nothing
	// landed" call for the same action from a caller — do not tag — and a
	// plausible wrong SHA is worse than an honest refusal, because a tag cannot
	// be quietly withdrawn.
	ResolveMergedCommit(ctx context.Context, owner, repo string, number int) (string, error)
}

type Release interface {
	GetName() string
	GetTagName() string
	GetBody() string
	GetDraft() bool
	GetAssets() []ReleaseAsset
}

type ReleaseAsset interface {
	GetID() int64
	GetName() string
	GetBrowserDownloadURL() string
}

type ReleaseAssetPublisher interface {
	// CreateReleaseWithAssets publishes a release carrying assets, such that NO
	// OBSERVER WITHOUT WRITE ACCESS EVER SEES IT WITHOUT THEM.
	//
	// That is the guarantee, and it is deliberately a statement about what is
	// observable rather than about how many requests are sent. Only one of the
	// three platforms can do it in a single request, and a contract promising
	// one would be honourable there and nowhere else:
	//
	//   - GitLab publishes the bytes to its package registry, which needs no
	//     release, then creates the release with every link in the same
	//     request. One visible state, and it is the complete one.
	//   - GitHub and Gitea create the release as a DRAFT, attach, then publish.
	//     A draft is not visible without write access on either platform, so
	//     from an observer's side the effect is the same.
	//
	// # Every rule CreateRelease states still applies
	//
	// The tag must already exist and is never created; draft.Commit is resolved
	// and compared rather than sent; a tag that already carries a release
	// returns [ErrAlreadyExists]. Read [ReleasePublisher.CreateRelease] for the
	// reasoning, all of which is unchanged.
	//
	// The tag check happens BEFORE any byte is uploaded. Uploading first and
	// finding the tag wrong afterwards would leave bytes in a package registry
	// for a release that was never created.
	//
	// # Read this before writing the usual error check
	//
	// Like CreateRelease, this returns the CREATED RELEASE together with an
	// error wrapping [ErrNotHonoured] when part of what was asked could not be
	// applied. The idiom that is correct:
	//
	//	rel, err := p.CreateReleaseWithAssets(ctx, owner, repo, draft, assets)
	//	if err != nil && !errors.Is(err, forge.ErrNotHonoured) {
	//	    return err // a real failure; nothing was created
	//	}
	//	// rel exists either way. Log err if non-nil: something was dropped.
	//
	// What it never does is succeed silently on a partial. The guarantee is the
	// whole point of the capability, so a release that went out incomplete says
	// so.
	//
	// # A Location the platform cannot hold becomes a footer, and is reported
	//
	// On GitHub and Gitea a [ReleaseAssetSource] carrying Location is rendered
	// as a link in a footer appended to the release body, and reported with
	// [ErrNotHonoured].
	//
	// Both halves matter. The footer keeps the location reachable by a human
	// reading the release; the error is owed to a machine, because
	// [Release.GetAssets] will NOT contain it and a caller enumerating assets
	// would otherwise be told nothing is missing when something is.
	//
	// The footer is written ONCE, here. [ReleasePublisher.UpdateRelease]
	// replaces the body wholesale, so an update that does not carry the footer
	// forward removes it — which regions of a body are machine-owned is the
	// caller's policy, as it is everywhere else in this contract.
	//
	// # A draft the CALLER asked for is honoured
	//
	// draft.Draft is intent, not merely the mechanism above. Where a platform
	// models it, a caller asking for a draft gets one carrying its assets: the
	// same route runs and the final publish step is not taken. GitLab models
	// neither draft nor prerelease and continues to report [ErrNotHonoured] for
	// them.
	//
	// # If an asset fails to attach, nothing is left behind
	//
	// On the platforms that take the draft route, a provider deletes the
	// unpublished draft it created rather than stranding the caller with a
	// half-built release that [ErrAlreadyExists] would block a retry against.
	// That is not a delete capability: nothing here lets a caller ask for a
	// deletion, and the only thing a provider may remove is a draft it created
	// moments earlier and never published. The tag is untouched.
	CreateReleaseWithAssets(
		ctx context.Context, owner, repo string, draft ReleaseDraft, assets []ReleaseAssetSource,
	) (Release, error)

	// AddReleaseAssetLocation attaches an ALREADY-HOSTED asset to the release on
	// tagName, which [ReleasePublisher.AddReleaseAsset] cannot express because
	// it takes an io.Reader.
	//
	// It is the after-the-fact sibling of the Location half above, and it
	// carries a limit that CreateReleaseWithAssets does not.
	//
	// # A source carrying Content is a CALLER ERROR here
	//
	// This method attaches a location. Handed a [ReleaseAssetSource] carrying
	// Content it refuses before any request is sent, and does NOT quietly
	// upload the bytes — doing that would silently become
	// [ReleasePublisher.AddReleaseAsset] and hide which of the two paths ran.
	//
	// The refusal is a plain error with no sentinel, exactly as
	// [ReleaseAssetSource.Validate] reports a malformed source, because a
	// caller cannot usefully branch on its own programming mistake. In
	// particular it is NOT [ErrNotFound]: on this method that sentinel means no
	// release exists for tagName, and reporting a wrong-shaped argument with it
	// sends a caller looking for a release that is right there.
	//
	// # There is no footer fallback here
	//
	// On a platform that cannot hold a location as an asset, this returns an
	// error wrapping [ErrNotHonoured] and writes NOTHING. It does not append a
	// footer, because doing so would mean reading the release body, modifying
	// it and writing it back — and that read-modify-write carries the
	// lost-update race [ReleasePublisher.UpdateRelease] already records as
	// unsolved, on every call.
	//
	// A caller that needs the location recorded on such a platform uses
	// CreateReleaseWithAssets, where the body is composed once and no existing
	// content can be lost.
	//
	// Returns an error wrapping [ErrNotFound] when no release exists for
	// tagName.
	AddReleaseAssetLocation(ctx context.Context, owner, repo, tagName string, asset ReleaseAssetSource) error
}

type ReleaseAssetSource struct {
	// Name is the asset's filename as it should appear on the release, and is
	// REQUIRED for both shapes.
	//
	// For a Location it is also the link text, so it is what a human sees.
	//
	// It is also what the platform's conventional asset address is derived
	// from — see [ReleaseAssetPublisher] — so it is the name a consumer will
	// write into a fetch URL, not merely a label.
	Name string

	// Size is the byte count, REQUIRED when Content is set and ignored
	// otherwise.
	//
	// Two of the platforms need it before the body and neither can obtain it
	// from a bare reader, which is why it is not optional and not derived.
	Size int64

	// Content is the asset's bytes. It is read EXACTLY ONCE and not seeked, so
	// a caller may stream a build artefact without landing it on disk first.
	//
	// Reading once is also why a [ReleaseAssetSource] carrying Content cannot be
	// reused across calls. A retry loop that re-sends the same value publishes
	// an empty asset from a drained reader, which is the failure this whole
	// capability exists to prevent, arriving one layer up.
	Content io.Reader

	// Location is an absolute http or https URL where the bytes already live.
	//
	// # This is not honoured everywhere, and the fallback is visible
	//
	// GitLab records it as a release asset link, which is that platform's
	// native asset. GitHub and Gitea have no concept of an asset that is a
	// link, so a provider there renders it into the release notes as a footer
	// and reports it with [ErrNotHonoured] — see [ReleaseAssetPublisher].
	//
	// # Nothing is fetched, and reachability is NEVER checked
	//
	// A provider does not download this URL to convert it into bytes, and it
	// does not HEAD it, resolve it, or otherwise confirm it serves anything.
	// That is a decision rather than an omission: the address is supplied by
	// whoever is publishing, and a request this module makes on their behalf to
	// a host it does not control is a capability nobody asked for — the same
	// reasoning that keeps a caller's HTTP client away from an asset URL.
	//
	// **So a forge will happily record a location that 404s.** The guarantee
	// this capability makes is that no observer sees the release before its
	// assets are ATTACHED; that the bytes are actually there is the caller's
	// guarantee, and it is the one worth checking before publishing rather than
	// after.
	//
	// What IS checked is shape: absolute, http or https, with a host. That
	// catches the mistake which would otherwise link to nothing at all, since a
	// relative path resolves against the forge's own host, and it costs no
	// request.
	//
	// Specified by spec 0016:
	// https://gitlab.com/phpboyscout/go/forge/-/wikis/specs/0016-assets-rules-the-contract-does-not-state
	Location string
}

type ReleaseDraft struct {
	// TagName is the tag the release is attached to. It MUST already exist;
	// see [ReleasePublisher.CreateRelease].
	TagName string

	// Commit is the full SHA that TagName is expected to point at, and it is
	// checked rather than sent.
	//
	// This field looks like it should tell the forge where to put the release,
	// and no forge will let it. On GitHub the equivalent parameter is
	// documented as "unused if the Git tag already exists"; GitLab behaves the
	// same way and does not say so, which was confirmed by creating a tag at
	// one commit and a release naming another — the request succeeded, returned
	// no warning, and the release sat on the tag's commit.
	//
	// So a provider MUST resolve TagName, compare what it points at against
	// this value, and return an error wrapping [ErrNotFound] on a mismatch.
	// That turns an instruction the forge may discard into a check it cannot
	// fake, which is the same reasoning as [PullRequests.ResolveMergedCommit]
	// one step later in the same workflow.
	//
	// A full SHA. A provider must reject a branch name or an abbreviation
	// rather than resolving it, because resolving is what reopens the race.
	Commit string

	// Name is the release's title. REQUIRED.
	//
	// GitHub and GitLab both accept an empty name; Gitea rejects one in its
	// SDK before the request is sent. Requiring it here means the same call
	// behaves the same way everywhere, rather than succeeding on two forges and
	// failing locally on the third.
	Name string

	// Body is the release notes, in the forge's markdown flavour.
	Body string

	// Draft asks for a release that is not yet published, and Prerelease for
	// one marked as not production-ready.
	//
	// GitHub and Gitea model both. GitLab models NEITHER — its create API has
	// no such field, which is a gap in the platform rather than in its client.
	//
	// A provider that cannot honour these MUST still create the release, and
	// MUST report what it could not apply by returning [ErrNotHonoured]
	// alongside the created release. It must not refuse, which would deny a
	// caller a release over a field the forge does not model, and it must not
	// stay silent, which would hand back a PUBLISHED release to a caller who
	// asked for a private one — on the one operation where that is expensive
	// and where [ReleasePublisher] offers no delete to undo it.
	Draft      bool
	Prerelease bool
}

type ReleasePublisher interface {
	// CreateRelease publishes a release for draft.TagName.
	//
	// # The tag must already exist
	//
	// CreateRelease returns an error wrapping [ErrNotFound] when the tag is
	// absent. It never creates one, and the reason is not only that tagging
	// belongs elsewhere.
	//
	// Given a tag that does not exist, a forge will happily create it from
	// whatever ref it was passed — so without this refusal, CreateRelease
	// silently becomes a tagging operation performed with the caller's credential, which
	// is precisely the credential whose writes may not fire the pipeline that
	// was meant to follow.
	//
	// Worse, creating is not atomic. A create that FAILS can still leave the
	// tag behind: a rejected asset link returned 400 with no release created,
	// and the tag it had been asked to create remained. A caller retrying then
	// finds a tag this contract wrote, and draft.Commit is checked against it —
	// a check against your own output proves nothing. Refusing an absent tag
	// removes the whole class instead of handling it.
	//
	// # Returns
	//
	// The created release, and one of:
	//
	//   - nil, when everything asked for was applied.
	//   - an error wrapping [ErrNotHonoured] TOGETHER WITH the created release,
	//     when the release exists but some field could not be applied. Read
	//     [ErrNotHonoured] before writing the usual error check.
	//   - an error wrapping [ErrAlreadyExists] when the tag already carries a
	//     release, [ErrNotFound] when the tag is absent or points somewhere
	//     other than draft.Commit, or a refusal sentinel. In every one of these
	//     the returned Release is nil and nothing was created.
	CreateRelease(ctx context.Context, owner, repo string, draft ReleaseDraft) (Release, error)

	// UpdateRelease amends an existing release's name and notes.
	//
	// It exists so notes can be corrected after the fact. It cannot move a
	// release to another commit, cannot change its tag, and there is no delete
	// — see the file comment for where that line sits and why.
	//
	// Returns an error wrapping [ErrNotFound] when no release exists for
	// tagName.
	UpdateRelease(ctx context.Context, owner, repo, tagName, name, body string) error

	// AddReleaseAsset attaches a file to the release on tagName.
	//
	// content is read exactly once and not seeked, so a caller may stream a
	// build artefact without landing it on disk first. size is the byte count
	// and is REQUIRED: two of the four platforms need it before the body, and
	// neither can obtain it from a bare reader.
	//
	// name is the asset's filename as it should appear on the release. A
	// provider derives the content type from its extension, falling back to
	// application/octet-stream.
	//
	// # This is not the same operation on every forge
	//
	// GitHub and Gitea accept a binary into the release. GitLab has no such
	// endpoint at all — its release assets are LINKS to files hosted elsewhere
	// — so a provider there uploads the bytes somewhere the instance will serve
	// them and links the result. That is a visible side effect rather than a
	// hidden one, and the provider's own documentation states where the file
	// lands.
	//
	// # The asset is reachable at the platform's conventional address
	//
	// Derived from name, on this method exactly as on
	// [ReleaseAssetPublisher], where the rule is stated in full along with
	// what a provider does when its platform cannot offer one.
	//
	// Returns an error wrapping [ErrNotFound] when no release exists for
	// tagName.
	AddReleaseAsset(ctx context.Context, owner, repo, tagName, name string, size int64, content io.Reader) error
}

type Repositories interface {
	// ListRepositories enumerates the repositories in a namespace, calling yield
	// once per repository. It paginates internally, so neither side holds the
	// whole namespace in memory. Returning false from yield stops the
	// enumeration early and is not an error; the provider must not call yield
	// again afterwards.
	//
	// Every yielded Repository.Path is WITHIN namespace: equal to it, or
	// prefixed by namespace + "/". This is a guarantee rather than an
	// observation, because at least one forge's default breaks it — GitLab's
	// project listing includes projects merely SHARED into a group unless
	// with_shared=false is passed, and those carry foreign paths. A caller
	// asking "is this in my namespace?" would otherwise get a different question
	// answered, in the permissive direction.
	//
	// namespace is opaque, and the provider RESOLVES it rather than guessing.
	// Where a forge splits organisations from users, the provider must determine
	// which it has before enumerating: on GitHub, an organisation the token
	// cannot see answers 404, and the user endpoint then succeeds for that same
	// name returning PUBLIC repositories only — a short list indistinguishable
	// from a complete one.
	//
	// The returned error is the single, complete answer to "did I see
	// everything?". It is ErrNotSupported when the capability is configured off,
	// and otherwise reports the first failure encountered. A nil error means the
	// namespace was enumerated in full; a NON-NIL error means the caller holds a
	// PARTIAL view and must not treat it as the namespace.
	//
	// That the error is an ordinary return value is deliberate. An iterator
	// yielding (Repository, error) can be ranged with a single variable, which
	// compiles cleanly, passes vet, discards every error and hands the caller a
	// zero-value Repository as though it were data — turning a failed
	// enumeration into a silently truncated one.
	ListRepositories(
		ctx context.Context,
		namespace string,
		opts RepositoryListOptions,
		yield func(Repository) bool,
	) error
}

type Repository struct {
	// Path is the canonical namespace path the API reported, and it is the
	// identity a caller keys on.
	//
	// It is the path that ANSWERED, which may not be the path that was asked
	// for: forges redirect renamed and transferred projects, so two paths can
	// resolve to one container. A caller that keys on anything else — a
	// directory name, a configured string, a remote URL — will eventually index
	// the same repository twice under two names.
	Path string

	// Name is the repository's short name, without the namespace.
	Name string

	// Description is the forge's one-line description, empty when unset.
	Description string

	// URL is the human-facing web URL, suitable for citations. Like
	// [GitRemote.CloneURL] it is API-reported data; pin it before attaching a
	// credential.
	URL string

	// Visibility is the forge's view of who can see this repository. Callers
	// making a security decision on it MUST allowlist — `v == VisibilityPublic`
	// — never denylist, since `v != VisibilityPrivate` admits both
	// [VisibilityUnknown] and [VisibilityInternal].
	Visibility Visibility

	// Archived reports the forge's own archived flag.
	//
	// It is false on a forge with no archiving concept — Bitbucket Cloud has
	// none — so it is a weak negative rather than a statement that the
	// repository is maintained.
	Archived bool

	// LastActivityAt is the most recent activity the provider reports, zero when
	// it reports none.
	//
	// It is BEST-EFFORT and NOT comparable across forges: GitLab reports
	// last_activity_at, GitHub pushed_at, Gitea updated_at and Bitbucket
	// updated_on — related, but not equivalent. Use it to spot abandonment,
	// never to order repositories from different forges against each other.
	LastActivityAt time.Time

	// Git carries the git remote. Its zero value means there is no git
	// repository behind this container, or the provider could not report one —
	// check Git.CloneURL before cloning rather than assuming.
	Git GitRemote

	// Site reports whether a documentation site is configured, from the
	// enumeration payload alone. See [SiteStatus] for why an empty value is not
	// "no site".
	Site SiteStatus
}

type RepositoryCreator interface {
	// CreateRepository creates a repository named draft.Name in owner.
	//
	// # owner is REQUIRED, and is a path
	//
	// It is the namespace path, exactly as every other method on this contract
	// takes one. Empty is an error rather than "my own namespace": Bitbucket has
	// no personal namespace for such a value to name, so a meaning that cannot
	// be honoured everywhere is not given one here.
	//
	// What each provider does with it is the provider's problem. GitLab resolves
	// the path to a numeric namespace id; GitHub and Gitea choose between a user
	// and an organisation endpoint by asking what the namespace IS; Bitbucket
	// uses it verbatim as the workspace slug.
	//
	// # Returns
	//
	// The created repository, and one of:
	//
	//   - nil, when everything asked for was applied.
	//   - an error wrapping [ErrNotHonoured] TOGETHER WITH the created
	//     repository, when it exists but some field could not be applied. Read
	//     [ErrNotHonoured] before writing the usual error check — the reflexive
	//     `if err != nil { return err }` treats a SUCCESSFUL creation as a
	//     failure, and a caller that then retries gets [ErrAlreadyExists] for a
	//     repository that was already correct.
	//   - an error wrapping [ErrAlreadyExists] when the name is taken, or a
	//     refusal sentinel. In both the returned Repository is the zero value and
	//     nothing was created.
	//
	// # The collision is FOUR forges and THREE status codes
	//
	// A provider maps its platform's answer rather than leaving a caller to
	// recognise four shapes, and it cannot do that from the status alone.
	// Measured by creating a repository and creating it again: GitLab answers
	// 400, GitHub 422, Gitea 409, Bitbucket 400. Only one of the four is the
	// status this looks like, and the two answering 400 share it with every
	// malformed request — so the body has to be read.
	//
	// # A created repository may not be readable immediately
	//
	// go-github documents that its create "will return the response without
	// actually waiting for GitHub to finish creating the repository". This
	// contract never retries, so a provider does not loop and the returned value
	// is what the create answered with. An immediate read-back on GitHub may not
	// find it. Three immediate reads did not reproduce it, and three immediate
	// reads on Gitea and Bitbucket did not either, so the caveat is GitHub's
	// alone — but it is the vendor's own warning and a caller should not build
	// a read-after-create assumption on one non-reproduction.
	//
	// # Initialise: false leaves no git repository
	//
	// The returned [Repository.Git] is then its zero value, which is what that
	// field's documented meaning already covers. Check Git.CloneURL before
	// cloning rather than assuming.
	CreateRepository(
		ctx context.Context, owner string, draft RepositoryDraft,
	) (Repository, error)
}

type RepositoryDraft struct {
	// Name is the repository's short name, without the namespace. REQUIRED.
	//
	// It is also the PATH SEGMENT, and that is a guarantee rather than an
	// accident of most forges agreeing. GitHub, Gitea and Bitbucket have one
	// field that is both; GitLab has two, a display `name` and a URL `path`,
	// and derives the second from the first by slugifying it. A provider there
	// MUST send this value as BOTH, because otherwise "My Tool" creates a
	// repository at my-tool and the returned Path is a value the caller never
	// wrote and cannot predict without knowing GitLab's slug rules.
	//
	// So the returned [Repository.Path] is always owner + "/" + Name. A caller
	// that wants a display name unlike its path is asking for post-creation
	// configuration, which this capability does not do.
	//
	// A provider rejects an empty Name before making any request, because a
	// forge's own answer to one is a validation error indistinguishable from a
	// dozen others.
	Name string

	// Description is the forge's one-line description. Empty sets none.
	Description string

	// Visibility is who should be able to see the repository.
	//
	// [VisibilityInternal] exists on GitLab and GitHub Enterprise only. A
	// provider that cannot honour it creates the repository PRIVATE — never
	// public — and reports with [ErrNotHonoured].
	//
	// Falling back to private rather than public is the whole of the reasoning:
	// the failure has to be safe, because there is no delete here to undo it.
	//
	// The zero value is [VisibilityUnknown], which a provider treats as private
	// for the same reason.
	Visibility Visibility

	// Initialise asks for a repository with a first commit, so it can be cloned
	// immediately.
	//
	// GitLab, GitHub and Gitea all offer this. BITBUCKET CANNOT: no such field
	// exists in its API, and a repository it creates has zero branches and zero
	// commits. A provider there creates the repository and reports the drop with
	// [ErrNotHonoured].
	Initialise bool

	// DefaultBranch is the branch a clone should land on. Empty takes the
	// platform's default.
	//
	// Honoured on GitLab and Gitea. GITHUB AND BITBUCKET BOTH ACCEPT IT AND
	// DISCARD IT — GitHub returns 201 with main, Bitbucket 200 with master,
	// neither with an error — so a provider there reports it with
	// [ErrNotHonoured]. That is the same trap [ReleaseDraft.Commit] exists to
	// close: a field a forge takes, ignores, and says nothing about.
	//
	// On Bitbucket it is unreachable rather than merely unimplemented. It
	// validates the name against branches that ACTUALLY EXIST — setting it after
	// creation answers 400 "not a valid branch" — and since it cannot
	// initialise, there is no branch for it to name. No ordering of calls this
	// contract can make will set it there.
	DefaultBranch string
}

type RepositoryListOptions struct {
	// IncludeSubgroups descends into nested namespaces. GitLab has them and
	// defaults to excluding them; GitHub, Gitea and Bitbucket have no equivalent
	// and ignore this.
	IncludeSubgroups bool

	// IncludeArchived includes archived repositories, which are excluded by
	// default.
	//
	// The default is a policy choice, so make it deliberately: a caller whose
	// own rules have no archived clause will silently lose qualifying
	// repositories by inheriting it.
	IncludeArchived bool

	// PageSize hints at the provider's internal page size. Zero means the
	// provider's own default. It tunes how many requests the enumeration makes,
	// never which repositories it returns.
	PageSize int
}

type SignatureProvider interface {
	// DownloadSignature returns the raw bytes of the detached
	// signature over the checksums manifest for the given release.
	//
	// As with [ChecksumProvider.DownloadChecksumManifest], the
	// implementation MUST enforce maxBytes. The two are deliberately
	// symmetric: an implementer should never have to remember which of the
	// two capped for them. [DefaultMaxSignatureSize] is a reasonable bound,
	// chosen by the caller.
	//
	// Returns [ErrNotSupported] when the provider is configured in a
	// way that disables signature retrieval (e.g. the Direct
	// provider's `signature_url_template` param is empty, or no
	// signature file was uploaded to Bitbucket). The caller treats
	// [ErrNotSupported] exactly like "provider does not implement this
	// interface" — fall back to asset-by-name lookup if one is
	// available, otherwise respect the require_signature policy.
	DownloadSignature(ctx context.Context, rel Release, maxBytes int64) ([]byte, error)
}

type Site struct {
	// URL is where the site is published, empty when the provider cannot say.
	//
	// It is the address to CITE: where the forge reports a configured domain,
	// this is that domain rather than the generated one. See [Site.URLSource]
	// for which of those it turned out to be.
	URL string

	// URLSource reports where URL came from, which is what tells a caller how
	// much a failed probe of it proves.
	//
	// The zero value is [SiteURLUnknown], so a Site nobody filled in claims
	// nothing about provenance.
	URLSource SiteURLSource

	// TLS reports whether the forge enforces HTTPS for this site.
	//
	// It is REPORTED, not applied: where the forge does not enforce, URL is
	// returned with the scheme the forge recorded rather than upgraded, because
	// upgrading would guess TLS availability on precisely the sites where the
	// forge declines to promise it. A caller that refuses to cite http:// has
	// what it needs to decide for itself.
	TLS SiteTLS

	// State describes how the most recent build ended, when the forge reports it.
	State SiteState

	// Visibility is who can see the site, which some forges control separately
	// from the container itself.
	Visibility Visibility
}

type SiteState string

type SiteStatus string

type SiteTLS string

type SiteURLSource string

type Sites interface {
	// GetSite returns the published-site details for a repository.
	//
	// Returns ErrNotSupported when the provider's forge has no site feature or
	// it is disabled for this configuration, and ErrNotFound when the repository
	// has no site. A permission failure is NEITHER — it is an error, so a caller
	// is never told "no site" because its token was too weak. On both forges
	// with a Pages API that distinction is routine rather than theoretical:
	// reading Pages settings requires elevated access.
	//
	// A non-error result means the forge reports a site as CONFIGURED. It never
	// means the site is reachable, and on a forge that infers configuration from
	// a convention rather than an API it may not even mean the site was ever
	// deployed — check State and URLSource before relying on it.
	GetSite(ctx context.Context, owner, repo string) (Site, error)
}

type Snippet struct {
	// ID identifies the snippet for later operations and is OPAQUE: GitLab uses
	// an integer, GitHub a hex string.
	//
	// A caller must not parse it, compare it across providers, or build a URL
	// from it — [Snippet.URL] is the address to cite.
	ID string

	// URL is where the snippet is published. This is the durable address a
	// consumer cites.
	URL string

	Title       string
	Description string

	// Visibility is the EFFECTIVE reachability, which is not always what the
	// forge's own field says.
	//
	// On GitLab a project snippet is subject to the project's snippets access
	// level as well as its own visibility, and the two are NOT reconciled by the
	// forge: a snippet capped to project members by that setting still reports
	// itself "public". A provider therefore computes this from both rather than
	// reading either, because reporting an artefact as world-readable when it is
	// not is the contract asserting something it has not checked.
	//
	// Neither setting can RAISE exposure, so the computed value is the more
	// restrictive of the two.
	Visibility SnippetVisibility

	// Files are the snippet's files. A provider MAY return them without content
	// from a listing, where fetching every body would cost a request per
	// snippet — see [Snippets.ListSnippets].
	Files []SnippetFile
}

type SnippetCreateOptions struct {
	// Title is required by both forges.
	Title string

	// Description is optional.
	Description string

	// Visibility is REQUIRED and has no default.
	//
	// [SnippetVisibilityUnknown] is rejected rather than resolved to whatever
	// the provider considers safest. The two forges disagree on what that would
	// even be, so a caller that omitted it would be publishing under a rule it
	// never read — and this is a write path, where that is not recoverable.
	Visibility SnippetVisibility

	// Files is the snippet's content, and must contain at least one file.
	Files []SnippetFile
}

type SnippetFile struct {
	// Path is the file's name as the forge will display it.
	Path string

	// Content is the file's bytes.
	//
	// Both forges' APIs are text-oriented; a provider given content they cannot
	// represent returns an error rather than writing something lossy.
	Content []byte
}

type SnippetScope struct {
	// Owner is the namespace — a user or group on GitLab, a user or
	// organisation on GitHub. Required for both scopes.
	Owner string

	// Repo selects the project scope. Empty means the account scope.
	Repo string
}

type SnippetVisibility string

type Snippets interface {
	// CreateSnippet creates a snippet and returns it, including the URL to cite
	// and the effective visibility achieved.
	//
	// Returns ErrNotSupported when the scope or the requested visibility is one
	// this forge cannot express — GitHub refuses both a project scope and
	// SnippetVisibilityPrivate. A provider MUST refuse rather than substitute
	// something weaker: a caller that asked for private and silently received a
	// world-readable URL does not find out until the artefact is published.
	//
	// The returned Visibility is the EFFECTIVE one and may be more restrictive
	// than requested — a project's own settings can cap it. It is never less
	// restrictive.
	CreateSnippet(ctx context.Context, scope SnippetScope, opts SnippetCreateOptions) (Snippet, error)

	// GetSnippet returns one snippet by its opaque ID, including file contents.
	//
	// Returns ErrNotFound when no such snippet exists. A permission refusal is
	// NOT ErrNotFound: a caller must never be told a snippet is absent because
	// its token was too weak.
	GetSnippet(ctx context.Context, scope SnippetScope, id string) (Snippet, error)

	// ListSnippets returns the snippets in scope.
	//
	// It paginates internally and returns the complete set. A NON-NIL error
	// means the slice is PARTIAL and must not be treated as the full set — the
	// same rule the enumeration capabilities carry, since a short list read as
	// complete is how something gets silently missed.
	//
	// File CONTENT may be absent from the returned snippets: fetching every body
	// costs a request per snippet, and a caller that wants one calls
	// GetSnippet. File paths are always populated.
	ListSnippets(ctx context.Context, scope SnippetScope) ([]Snippet, error)

	// DeleteSnippet removes a snippet by its opaque ID.
	//
	// Returns ErrNotFound when no such snippet exists, so a caller cleaning up
	// can treat "already gone" as success rather than a failure to investigate.
	DeleteSnippet(ctx context.Context, scope SnippetScope, id string) error
}

type TrustOption func(*trustPolicy)

type Visibility string

type WikiPage struct {
	// Path identifies the page, and is the ONLY identity this contract has —
	// "specs/0079-pipeline-churn", with no extension and no leading slash.
	//
	// It is what a caller writes and what it reads back. How each platform
	// stores and displays it varies and is the provider's problem:
	//
	//	GitLab      a native nested slug
	//	Gitea       one escaped filename; written by title, READ BY sub_url
	//	GitHub      a file at <path>.md, whose rendered page name drops the
	//	            directory — the file keeps it, the wiki UI does not
	//
	// The Gitea case is the one that bites. Its write and read paths are not
	// inverses: a title containing a hyphen gains a ".-" marker on write that a
	// read by the same string does not reproduce, so reading back what you just
	// wrote returns 404 for every "NNNN-slug" name. The adapter keeps the
	// sub_url the API handed it and keys on that. Measured on Gitea 1.24.7.
	Path string

	// Content is the page body, in the forge's markdown flavour.
	//
	// It is EMPTY in the pages returned by [Wikis.ListWikiPages]: fetching every
	// body costs a request per page, and a caller that wants one calls
	// [Wikis.GetWikiPage]. The same rule [Snippets.ListSnippets] follows.
	Content string
}

type Wikis interface {
	// ListWikiPages returns every page in the project's wiki.
	//
	// It paginates internally and returns the complete set. A NON-NIL error
	// means the slice is PARTIAL and must not be read as the full set, which is
	// the rule every enumeration in this contract carries.
	//
	// WikiPage.Content is empty in the result. See [WikiPage.Content].
	ListWikiPages(ctx context.Context, owner, repo string) ([]WikiPage, error)

	// GetWikiPage returns one page and its content.
	//
	// maxBytes is REQUIRED and the provider MUST enforce it, for the same
	// reason [Contents.GetFile] does: every remote read in this module is
	// bounded by a caller-supplied ceiling, enforced at the trust boundary by
	// the only code that sees the response before it is buffered.
	// [DefaultMaxFileSize] is a reasonable value, and the CALLER chooses.
	//
	// Returns an error wrapping [ErrNotFound] when no page exists at path — an
	// ordinary answer to "is this page there yet?", not a failure.
	GetWikiPage(ctx context.Context, owner, repo, path string, maxBytes int64) (WikiPage, error)

	// CreateWikiPage adds a page.
	//
	// message is the commit the write should carry. Not every forge models one:
	// GitLab's wiki options are content, title and format and nothing else, so
	// a provider there writes the page and reports the dropped message with
	// [ErrNotHonoured]. Read that sentinel before writing the usual error check
	// — the page EXISTS when it comes back.
	//
	// A provider reports it only when a message was actually supplied. Firing it
	// on every write for a field the caller left empty teaches callers to ignore
	// the sentinel.
	//
	// Returns an error wrapping [ErrAlreadyExists] when the path is taken, so a
	// caller can fall through to [Wikis.UpdateWikiPage] rather than guessing.
	CreateWikiPage(ctx context.Context, owner, repo string, page WikiPage, message string) error

	// UpdateWikiPage replaces a page's content.
	//
	// Returns an error wrapping [ErrNotFound] when no page exists at
	// page.Path, one wrapping [ErrConflict] when the wiki changed between the
	// provider's read and its write, and one wrapping [ErrNotHonoured] when the
	// page was written and message could not be — see [Wikis.CreateWikiPage].
	//
	// # The conflict is real on the git-backed forges
	//
	// GitHub and Bitbucket are served by clone, edit, push — a read-modify-write
	// across a network. A second writer in that window makes the push a
	// non-fast-forward, and it MUST surface as [ErrConflict] rather than be
	// retried or, worse, forced. Last-write-wins on a wiki carrying a project's
	// decision records is the failure this capability exists to prevent,
	// arriving by another route.
	//
	// A provider narrows the window by re-reading immediately before it writes.
	// It cannot close it, and does not pretend to.
	UpdateWikiPage(ctx context.Context, owner, repo string, page WikiPage, message string) error
}