docs(stovepipe): trim queue transition commentary

Author: mnoah1

stovepipe/core/queuelog/materializer.go

@@ -27,23 +27,21 @@ import (
 	"github.com/uber/submitqueue/stovepipe/extension/storage"
 )
 
-// ErrInconsistentHistory identifies missing or conflicting committed occurrences or projections.
+// ErrInconsistentHistory identifies missing or conflicting queue history or summaries.
 var ErrInconsistentHistory = errors.New("inconsistent queue history")
 
-// Materializer retains committed queue occurrences and advances their derived summary.
+// Materializer retains committed state changes and updates their summary.
 type Materializer interface {
 	// PersistLog idempotently retains an occurrence, then projects its state.
 	PersistLog(context.Context, storage.Storage, entity.QueueLog) error
 }
 
 type materializer struct{ scope tally.Scope }
 
-// NewMaterializer creates a queue history materializer with bounded outcome metrics.
 func NewMaterializer(scope tally.Scope) Materializer {
 	return &materializer{scope: scope.SubScope("queue_log_materializer")}
 }
 
-// NewQueueStateLog represents the committed enablement occurrence in an internal queue snapshot.
 func NewQueueStateLog(queue entity.Queue) entity.QueueLog {
 	return entity.QueueLog{ID: entity.QueueLogID(queue.EnablementVersion), Queue: queue.Name,
 		State: queue.Enablement, QueueStateVersion: queue.EnablementVersion,

stovepipe/core/queuelog/queue_summary.go

@@ -22,7 +22,7 @@ import (
 	"github.com/uber/submitqueue/stovepipe/extension/storage"
 )
 
-// LoadSummary pins a valid read model and verifies its occurrence without writing or consulting internal state.
+// LoadSummary requires the summary to match its retained history entry.
 func LoadSummary(ctx context.Context, stores storage.Storage, queue string) (entity.QueueState, error) {
 	if err := ctx.Err(); err != nil {
 		return entity.QueueState{}, err
@@ -47,7 +47,7 @@ func LoadSummary(ctx context.Context, stores storage.Storage, queue string) (ent
 	return summary.Snapshot(), nil
 }
 
-// LoadVersion reads a retained occurrence by its queue-scoped enablement sequence.
+// LoadVersion returns ErrInconsistentHistory for missing or invalid history.
 func LoadVersion(ctx context.Context, logs storage.QueueLogStore, queue string, version int64) (entity.QueueState, error) {
 	log, err := logs.Get(ctx, entity.QueueLogID(version))
 	if err != nil {

stovepipe/core/queuestate/queuestate.go

@@ -54,7 +54,6 @@ type transitionController struct {
 	now           func() time.Time
 }
 
-// NewTransitionController constructs the internal writer over an injected read-model materializer.
 func NewTransitionController(stores storage.Factory, sc sourcecontrol.Factory, materializer queuelog.Materializer) TransitionController {
 	return &transitionController{stores: stores, sourceControl: sc, materializer: materializer, now: time.Now}
 }
@@ -200,7 +199,7 @@ func (c *transitionController) Apply(ctx context.Context, change PreparedChange)
 		if err := c.validatePreparedBoundary(ctx, change); err != nil {
 			return entity.QueueState{}, err
 		}
-		// Recopy the latest operational fields; only enablement is pinned by the prepared decision.
+		// An enablement change must preserve concurrent pipeline updates.
 		updated := internal
 		updated.Enablement, updated.EnablementVersion = change.next.State, stateVersion
 		updated.EffectiveFromCommitURI, updated.EnablementChangedAtMs = change.next.EffectiveFromCommitURI, change.next.ChangedAtMs

stovepipe/core/queuestate/queuestate_test.go

@@ -275,7 +275,6 @@ func TestStatePartialLogWriteBlocksNextTransition(t *testing.T) {
 	require.Equal(t, int64(2), f.state.Version)
 	f.logCreateErr = nil
 	f.clock = 9000
-	// A no-op also repairs the occurrence before returning.
 	noop, err := f.manager.Prepare(context.Background(), "repo/main", entity.QueueEnablementEnabled)
 	require.NoError(t, err)
 	_, err = f.manager.Apply(context.Background(), noop)

test/integration/stovepipe/extension/storage/mysql/queue_state_transitions_test.go

@@ -61,7 +61,6 @@ func testQueueStateTransitions(t *testing.T, ctx context.Context, db *sql.DB, ba
 	disabled, err := manager.Apply(ctx, disable)
 	require.NoError(t, err)
 	require.Equal(t, int64(3), disabled.Version)
-	// A new manager can replay the captured decision without selecting a new boundary.
 	restarted := queuestate.NewTransitionController(mysqlFactory{backend: backend}, source, queuelog.NewMaterializer(tally.NoopScope))
 	replay, err := restarted.Apply(ctx, enable)
 	require.NoError(t, err)