fix(stovepipe): reverse BuildRunner.Trigger arg order, trim README

Author: roychying

stovepipe/extension/buildrunner/README.md

@@ -1,21 +1,11 @@
 # BuildRunner
 
-Vendor-agnostic interface through which Stovepipe triggers and polls builds against an external build system. Shaped the same as SubmitQueue's own `buildrunner` extension — same `Trigger`/`Status`/`Cancel` verbs, same async contract, same id model — but a separate interface rather than a shared one: Stovepipe validates a single commit against a baseline (or from scratch), not a stack of dependency batches, so `Trigger` takes URI identity instead of batch identity. See [doc/rfc/stovepipe/steps/build.md](../../../doc/rfc/stovepipe/steps/build.md#why-separate-contracts) for the full rationale, and its ["Carries over vs. new"](../../../doc/rfc/stovepipe/steps/build.md#carries-over-vs-new) section for what is shaped the same as SubmitQueue's versus what is Stovepipe-specific.
+Vendor-agnostic interface through which Stovepipe triggers and polls builds against an external build system.
 
-Per the repository's extension rules, this package holds the `BuildRunner` interface, its `Config`, and the `Factory` *interface* only — concrete `Factory` implementations and the per-queue routing that picks a backend for a `Config.QueueName` live in the wiring layer.
-
-## Behavior
-
-- **Trigger** starts a new build against `headURI` (optionally relative to an incremental `baseURI`) and returns the runner-minted build id. There is no caller-supplied dedup input — every call starts a fresh build, and downstream idempotency absorbs any duplicate from a redelivery. Trigger must return promptly; the build itself runs asynchronously.
+- **Trigger** starts a new build against `headURI`, optionally relative to an incremental `baseURI`, and returns the runner-minted build id. There is no caller-supplied dedup input — every call starts a fresh build; downstream idempotency absorbs any duplicate from a redelivery. Trigger must return promptly; the build itself runs asynchronously.
 - **Status** polls the current status and any provider metadata for a build id `Trigger` returned. Unlike `Trigger`, it may round-trip to the backend and block.
-- **Cancel** requests cancellation for a build id, returning once the request reaches the runner rather than once the build actually stops. No controller calls it today — it exists for contract parity with SubmitQueue and for future use.
-
-## Errors
-
-Implementations return plain, unclassified errors — the calling controller decides user-vs-infra and retryable-vs-not, per `platform/errs`. There is no package error sentinel yet; a domain sentinel (e.g. for "unknown build") is deferred until a concrete need for it lands.
-
-## Implementations
+- **Cancel** requests cancellation for a build id, returning once the request reaches the runner rather than once the build actually stops. Unused today; kept for contract parity with SubmitQueue.
 
-- **fake** — a stateless backend that succeeds by default and honors failure-injection markers embedded in `headURI`, for examples and tests.
+Implementations return plain, unclassified errors — the calling controller decides retryable-vs-not and user-vs-infra, per `platform/errs`.
 
-To add a backend, create `buildrunner/{backend}/`, implement the `BuildRunner` interface, and return it from a `New(...)` constructor.
+See [doc/rfc/stovepipe/steps/build.md](../../../doc/rfc/stovepipe/steps/build.md#why-separate-contracts) for why this is a separate contract from SubmitQueue's own `buildrunner` rather than a shared one. To add a backend, create `buildrunner/{backend}/`, implement `BuildRunner`, and return it from a `New(...)` constructor.

stovepipe/extension/buildrunner/buildrunner.go

@@ -43,13 +43,13 @@ import (
 //     platform/errs.
 type BuildRunner interface {
 	// Trigger starts a new build every call and mints the build's identity —
-	// there is no caller-supplied dedup input. headURI is the commit under
-	// validation; baseURI is the incremental baseline, empty for a full
-	// build; both are opaque tokens owned by SourceControl. metadata is
+	// there is no caller-supplied dedup input. baseURI is the incremental
+	// baseline, empty for a full build; headURI is the commit under
+	// validation; both are opaque tokens owned by SourceControl. metadata is
 	// caller-supplied annotation the runner may echo back via Status but must
 	// not depend on. Trigger is async: it must return promptly with the
 	// runner-assigned id, not an outcome — callers learn progress via Status.
-	Trigger(ctx context.Context, headURI, baseURI string, metadata entity.BuildMetadata) (entity.BuildID, error)
+	Trigger(ctx context.Context, baseURI, headURI string, metadata entity.BuildMetadata) (entity.BuildID, error)
 
 	// Status returns the build's current status and any provider metadata for
 	// the id Trigger returned. Unlike Trigger, Status may round-trip to the

stovepipe/extension/buildrunner/fake/fake.go

@@ -71,7 +71,7 @@ func New() buildrunner.BuildRunner {
 // returns a unique BuildID that encodes the terminal outcome the build should
 // report at Status time (decided from the headURI marker). baseURI and metadata
 // are ignored.
-func (r runner) Trigger(_ context.Context, headURI, _ string, _ entity.BuildMetadata) (entity.BuildID, error) {
+func (r runner) Trigger(_ context.Context, _, headURI string, _ entity.BuildMetadata) (entity.BuildID, error) {
 	outcome := outcomeOK
 	switch marker(headURI) {
 	case tokenTriggerError:

stovepipe/extension/buildrunner/fake/fake_test.go

@@ -42,7 +42,7 @@ func TestTrigger(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			id, err := New().Trigger(context.Background(), tt.headURI, "", nil)
+			id, err := New().Trigger(context.Background(), "", tt.headURI, nil)
 			if tt.wantErr {
 				require.Error(t, err)
 				assert.Empty(t, id.ID)
@@ -55,9 +55,9 @@ func TestTrigger(t *testing.T) {
 }
 
 func TestTrigger_UniqueIDs(t *testing.T) {
-	a, err := New().Trigger(context.Background(), "git://repo/ref/deadbeef", "", nil)
+	a, err := New().Trigger(context.Background(), "", "git://repo/ref/deadbeef", nil)
 	require.NoError(t, err)
-	b, err := New().Trigger(context.Background(), "git://repo/ref/deadbeef", "", nil)
+	b, err := New().Trigger(context.Background(), "", "git://repo/ref/deadbeef", nil)
 	require.NoError(t, err)
 	assert.NotEqual(t, a.ID, b.ID)
 }
@@ -75,7 +75,7 @@ func TestStatus(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			id, err := New().Trigger(context.Background(), tt.headURI, "", nil)
+			id, err := New().Trigger(context.Background(), "", tt.headURI, nil)
 			require.NoError(t, err)
 
 			status, metadata, err := New().Status(context.Background(), id)
@@ -98,7 +98,7 @@ func TestStatus_UnrecognizedIDSucceeds(t *testing.T) {
 }
 
 func TestStatus_StatelessAcrossInstances(t *testing.T) {
-	id, err := New().Trigger(context.Background(), "git://repo/ref/deadbeef?buildrunner-fake=build-fail", "", nil)
+	id, err := New().Trigger(context.Background(), "", "git://repo/ref/deadbeef?buildrunner-fake=build-fail", nil)
 	require.NoError(t, err)
 
 	status, _, err := New().Status(context.Background(), id)