[5/N] feat(sqsim): add modeled runtime primitives

sqsim/model/BUILD.bazel

@@ -0,0 +1,45 @@
+load("@rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "go_default_library",
+    srcs = [
+        "clock.go",
+        "error.go",
+        "profile.go",
+        "runtime.go",
+        "sequence.go",
+        "state.go",
+        "timeline.go",
+        "uri.go",
+    ],
+    importpath = "github.com/uber/submitqueue/sqsim/model",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//platform/errs:go_default_library",
+        "//sqsim:go_default_library",
+        "//sqsim/entity:go_default_library",
+    ],
+)
+
+go_test(
+    name = "go_default_test",
+    srcs = [
+        "clock_test.go",
+        "error_test.go",
+        "profile_test.go",
+        "runtime_test.go",
+        "sequence_test.go",
+        "state_test.go",
+        "timeline_test.go",
+        "uri_test.go",
+    ],
+    embed = [":go_default_library"],
+    deps = [
+        "//platform/errs:go_default_library",
+        "//sqsim:go_default_library",
+        "//sqsim/entity:go_default_library",
+        "//sqsim/scenarios:go_default_library",
+        "@com_github_stretchr_testify//assert:go_default_library",
+        "@com_github_stretchr_testify//require:go_default_library",
+    ],
+)

sqsim/model/clock.go

@@ -0,0 +1,51 @@
+// Copyright (c) 2026 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package model
+
+import (
+	"context"
+	"time"
+)
+
+// Clock supplies wall time and cancellable waits to modeled operations.
+type Clock interface {
+	// Now returns the current wall time.
+	Now() time.Time
+	// Wait blocks for the duration or until the context is cancelled.
+	Wait(ctx context.Context, duration time.Duration) error
+}
+
+// RealClock uses the process wall clock.
+type RealClock struct{}
+
+// Now returns the current wall time.
+func (RealClock) Now() time.Time {
+	return time.Now()
+}
+
+// Wait blocks for the duration or until the context is cancelled.
+func (RealClock) Wait(ctx context.Context, duration time.Duration) error {
+	if duration <= 0 {
+		return nil
+	}
+	timer := time.NewTimer(duration)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}

sqsim/model/clock_test.go

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package model
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestRealClockWaitHonorsCancellation(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	err := (RealClock{}).Wait(ctx, time.Hour)
+	require.ErrorIs(t, err, context.Canceled)
+}

sqsim/model/error.go

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package model
+
+import (
+	"fmt"
+
+	"github.com/uber/submitqueue/platform/errs"
+	"github.com/uber/submitqueue/sqsim/entity"
+)
+
+// FaultError is an external-system failure selected by a scenario.
+type FaultError struct {
+	// Kind identifies retryability.
+	Kind entity.FaultKind
+	// Phase identifies whether the modeled side effect happened.
+	Phase entity.FaultPhase
+}
+
+// Error describes the modeled failure.
+func (e *FaultError) Error() string {
+	return fmt.Sprintf("sqsim modeled %s fault %s", e.Kind, e.Phase)
+}
+
+// ErrorForFault returns the typed error selected by fault.
+func ErrorForFault(fault entity.Fault) error {
+	if fault.Kind == entity.FaultNone {
+		return nil
+	}
+	return &FaultError{Kind: fault.Kind, Phase: fault.Phase}
+}
+
+// Classifier classifies modeled external-system errors.
+var Classifier errs.Classifier = classifier{}
+
+type classifier struct{}
+
+func (classifier) Classify(err error) errs.Verdict {
+	fault, ok := err.(*FaultError)
+	if !ok {
+		return errs.Unknown
+	}
+	switch fault.Kind {
+	case entity.FaultRetryable:
+		return errs.InfraDependencyRetryable
+	case entity.FaultNonRetryable:
+		return errs.InfraDependency
+	default:
+		return errs.Unknown
+	}
+}

sqsim/model/error_test.go

@@ -0,0 +1,44 @@
+// Copyright (c) 2026 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package model
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/uber/submitqueue/platform/errs"
+	"github.com/uber/submitqueue/sqsim/entity"
+)
+
+func TestClassifierClassifiesModeledFaults(t *testing.T) {
+	tests := []struct {
+		name      string
+		kind      entity.FaultKind
+		retryable bool
+	}{
+		{name: "retryable", kind: entity.FaultRetryable, retryable: true},
+		{name: "non-retryable", kind: entity.FaultNonRetryable, retryable: false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			raw := ErrorForFault(entity.Fault{Kind: tt.kind, Phase: entity.FaultBeforeSideEffect})
+			require.Error(t, raw)
+			classified := errs.NewClassifierProcessor(Classifier).Process(raw)
+			assert.Equal(t, tt.retryable, errs.IsRetryable(classified))
+			assert.True(t, errs.IsDependencyError(classified))
+		})
+	}
+}

sqsim/model/profile.go

@@ -0,0 +1,119 @@
+// Copyright (c) 2026 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package model
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+
+	"github.com/uber/submitqueue/sqsim"
+	"github.com/uber/submitqueue/sqsim/entity"
+)
+
+// Profile is the immutable scenario input shared with SQSim adapters.
+type Profile struct {
+	// Name is the public scenario registry name.
+	Name string `json:"name"`
+	// Scenario is the workload and modeled external behavior.
+	Scenario entity.Scenario `json:"scenario"`
+}
+
+// Compile validates a named scenario and returns its runtime profile.
+func Compile(name string, scenario sqsim.Scenario) (Profile, error) {
+	if err := validateName("scenario", name); err != nil {
+		return Profile{}, err
+	}
+	if err := sqsim.Validate(scenario); err != nil {
+		return Profile{}, fmt.Errorf("validate scenario: %w", err)
+	}
+	return cloneProfile(Profile{Name: name, Scenario: scenario}), nil
+}
+
+// Write writes a profile as JSON to path.
+func Write(path string, profile Profile) error {
+	if path == "" {
+		return fmt.Errorf("profile path is required")
+	}
+	if err := validateProfile(profile); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(profile, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshal profile: %w", err)
+	}
+	data = append(data, '\n')
+	if err := os.WriteFile(path, data, 0o600); err != nil {
+		return fmt.Errorf("write profile: %w", err)
+	}
+	return nil
+}
+
+// Load reads and validates a profile from path.
+func Load(path string) (Profile, error) {
+	if path == "" {
+		return Profile{}, fmt.Errorf("profile path is required")
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return Profile{}, fmt.Errorf("read profile: %w", err)
+	}
+	var profile Profile
+	if err := json.Unmarshal(data, &profile); err != nil {
+		return Profile{}, fmt.Errorf("decode profile: %w", err)
+	}
+	if err := validateProfile(profile); err != nil {
+		return Profile{}, err
+	}
+	return cloneProfile(profile), nil
+}
+
+func validateProfile(profile Profile) error {
+	if err := validateName("scenario", profile.Name); err != nil {
+		return err
+	}
+	if err := sqsim.Validate(profile.Scenario); err != nil {
+		return fmt.Errorf("validate scenario: %w", err)
+	}
+	return nil
+}
+
+func cloneProfile(profile Profile) Profile {
+	lands := make([]entity.Land, len(profile.Scenario.Lands))
+	for i, land := range profile.Scenario.Lands {
+		lands[i] = cloneLand(land)
+	}
+	profile.Scenario.Lands = lands
+	return profile
+}
+
+func cloneLand(land entity.Land) entity.Land {
+	triggers := make([]entity.Invocation[entity.BuildTriggerOutcome], len(land.Behavior.BuildRunner.Triggers))
+	for i, trigger := range land.Behavior.BuildRunner.Triggers {
+		trigger.Outcome.Build.Timeline = append([]entity.BuildStatusPoint(nil), trigger.Outcome.Build.Timeline...)
+		trigger.Outcome.Build.StatusFaults = append([]entity.FaultOnCall(nil), trigger.Outcome.Build.StatusFaults...)
+		triggers[i] = trigger
+	}
+	land.Behavior.BuildRunner.Triggers = triggers
+	land.Behavior.MergeConflictCheck.Invocations = append(
+		[]entity.Invocation[entity.MergeConflictCheckOutcome](nil),
+		land.Behavior.MergeConflictCheck.Invocations...,
+	)
+	land.Behavior.Merge.Invocations = append(
+		[]entity.Invocation[entity.MergeOutcome](nil),
+		land.Behavior.Merge.Invocations...,
+	)
+	return land
+}