Merge pull request #92 from MB3R-Lab/fixed-k-replica-slots

a-a-k · web-flow · commit 7f3e8e447762 · 2026-07-02T22:05:18.000+03:00
Add fixed replica slot sampling
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## v1.1.0 - 2026-07-02
+
+- added `fixed_k_replica_slots` sampling for fixed-fraction experiment reproduction; when `fixed_k_failures` is omitted, Sheaft derives `k = ceil(failure_probability * total_replica_slots)`
+- added schema, methodology, configuration example, and simulation coverage for fixed replica-slot sampling
+- kept Bering contract compatibility unchanged on the strict `io.mb3r.bering.model@1.3.0` and `io.mb3r.bering.snapshot@1.3.0` line
+
+## v1.0.0 - 2026-07-02
+
 - added v1 major semantics documentation for the stochastic connectivity baseline, migration notes, and explicit out-of-scope release boundaries
 - added release dry-run validation for v1 docs/schema/example consistency
 - recorded app-level sync with Bering `v1.0.0` in `compatibility-manifest.json`
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Sheaft
 
-[![release](https://img.shields.io/badge/release-v1.0.0-blue)](https://github.com/MB3R-Lab/Sheaft/releases/tag/v1.0.0)
+[![release](https://img.shields.io/badge/release-v1.1.0-blue)](https://github.com/MB3R-Lab/Sheaft/releases/tag/v1.1.0)
 [![checks](https://img.shields.io/github/actions/workflow/status/MB3R-Lab/Sheaft/release-dry-run.yml?branch=main&label=checks)](https://github.com/MB3R-Lab/Sheaft/actions/workflows/release-dry-run.yml)
 [![bering schema](https://img.shields.io/badge/bering%20schema-1.3.0-blue)](https://github.com/MB3R-Lab/Sheaft/blob/main/docs/compatibility-matrix.md)
 
@@ -21,20 +21,21 @@ It stays downstream of topology discovery. The public surface in this repository
 
 ## Stability / Release Status
 
-The current public release line is `v1.0.0`. It is the first major Sheaft line for the stochastic-connectivity baseline over Bering `1.3.0` model and snapshot contracts.
+The current public release line is `v1.1.0`. It is the current stable Sheaft line for the stochastic-connectivity baseline over Bering `1.3.0` model and snapshot contracts.
 
-Stable in `v1.0.0`:
+Stable in `v1.1.0`:
 
 - strict acceptance of the Bering v1 contract line: `io.mb3r.bering.model@1.3.0` and `io.mb3r.bering.snapshot@1.3.0`
 - batch CLI command names and core flow: `simulate`, `gate`, `run`
 - deterministic batch execution for a fixed seed and config
+- fixed replica-slot sampling through `sampling_mode: fixed_k_replica_slots` for reproducing fixed-fraction experiment protocols
 - baseline comparison through `analysis.baselines` for supported `1.3.0` artifacts
 - additive advanced analysis when `1.3.0` metadata exists
 - gate decision reasons in `report.json`, `summary.md`, and `sheaft gate/run --why`
 - fixed benchmark slice and release-quality `quality-report.json` generation
 - release archives for Linux and macOS on `amd64` and `arm64`
 
-Outside the stable `v1.0.0` release claim:
+Outside the stable `v1.1.0` release claim:
 
 - long-running `serve` posture service as a long-term operations contract
 - richer analysis configuration ergonomics beyond the shipped examples
diff --git a/api/schema/analysis.schema.json b/api/schema/analysis.schema.json
@@ -25,7 +25,8 @@
       "enum": [
         "independent_replica",
         "independent_service",
-        "fixed_k_service_set"
+        "fixed_k_service_set",
+        "fixed_k_replica_slots"
       ]
     },
     "failure_probability": {
@@ -91,7 +92,8 @@
             "enum": [
               "independent_replica",
               "independent_service",
-              "fixed_k_service_set"
+              "fixed_k_service_set",
+              "fixed_k_replica_slots"
             ]
           },
           "failure_probability": {
diff --git a/configs/analysis.example.yaml b/configs/analysis.example.yaml
@@ -24,6 +24,9 @@ profiles:
   - name: fixed-blast-radius
     sampling_mode: fixed_k_service_set
     fixed_k_failures: 1
+  - name: experiment-fixed-fraction
+    sampling_mode: fixed_k_replica_slots
+    failure_probability: 0.30
 
 gate:
   mode: warn
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -41,6 +41,13 @@ Profile-level `reliability` values inherit the top-level block and can override
 
 For artifact baseline comparisons, prefer homogeneous `reliability.edge_live_probability` unless every compared artifact exposes the same edge IDs. Per-edge `reliability.edges` entries are validated against each artifact under analysis.
 
+Sampling modes:
+
+- `independent_replica`: replicas fail independently; a service stays live while any replica survives
+- `independent_service`: each service is sampled once per trial regardless of replica count
+- `fixed_k_service_set`: exactly `fixed_k_failures` services fail per trial
+- `fixed_k_replica_slots`: exactly `k` replica slots fail per trial; when `fixed_k_failures` is omitted, `k = ceil(failure_probability * total_replica_slots)`
+
 ## Serve Config
 
 Use the versioned serve config for long-running posture mode:
diff --git a/docs/consumer-semantics-v1.md b/docs/consumer-semantics-v1.md
@@ -332,7 +332,22 @@ Expected outcome:
 - exactly one service fails each trial;
 - a single-path endpoint that depends on all three services has availability `0`.
 
-### 14. Gate threshold precedence is profile-specific first
+### 14. `fixed_k_replica_slots` fails a fixed number of replica slots
+
+Input:
+
+- one service with `replicas=2`;
+- `sampling_mode: fixed_k_replica_slots`;
+- `failure_probability: 0.5`;
+- `fixed_k_failures` omitted.
+
+Expected outcome:
+
+- Sheaft derives `fixed_k_failures = ceil(0.5 * 2) = 1`;
+- exactly one replica slot fails each trial;
+- the service remains available because one replica slot survives.
+
+### 15. Gate threshold precedence is profile-specific first
 
 Input:
 
@@ -343,7 +358,7 @@ Expected outcome:
 - the profile-specific endpoint threshold is applied for that profile;
 - otherwise endpoint-specific threshold wins over global threshold.
 
-### 15. `evaluation_rule=all_profiles` differs from `evaluation_rule=any_profile`
+### 16. `evaluation_rule=all_profiles` differs from `evaluation_rule=any_profile`
 
 Input:
 
diff --git a/docs/methodology.md b/docs/methodology.md
@@ -27,8 +27,9 @@ For each configured profile Sheaft:
 - `independent_replica`: replicas fail independently and a service stays available while any replica survives
 - `independent_service`: each service is sampled once per trial regardless of replica count
 - `fixed_k_service_set`: exactly `k` services fail per trial
+- `fixed_k_replica_slots`: exactly `k` replica slots fail per trial; when `fixed_k_failures` is omitted, `k = ceil(failure_probability * total_replica_slots)`
 
-When `1.3.0` placement buckets exist, `independent_replica` samples those buckets explicitly. A service remains effectively alive while at least one bucket still has a live replica.
+When `1.3.0` placement buckets exist, replica-based modes sample those buckets explicitly. A service remains effectively alive while at least one bucket still has a live replica.
 
 ## Stochastic Connectivity Parameters
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -72,7 +72,7 @@ The published `v0.2.4` release payload is the previous preview baseline:
 | Issue | GitHub state | Repo reality | Notes |
 | --- | --- | --- | --- |
 | R1.1 | closed | done | "Consumer Semantics v1" is documented in-repo with version scope, precedence rules, and 15 expected behavior examples. |
-| R1.2 | closed | done | Fail-stop baseline semantics, three sampling modes, timeout/partial degradation handling, and the external Sheaft fault contract are implemented and tested. |
+| R1.2 | closed | done | Fail-stop baseline semantics, four sampling modes, timeout/partial degradation handling, and the external Sheaft fault contract are implemented and tested. |
 | R1.3 | open | partial | Retry/timeout/circuit-breaker inputs from Bering `1.3.0` and the Sheaft fault contract are now handled; fallback/rate-limit annotations still remain outside the implemented surface. |
 
 ### R2. Model discovery from artifacts
diff --git a/docs/v1-major-semantics.md b/docs/v1-major-semantics.md
@@ -25,7 +25,7 @@ The implementation is deterministic for a fixed artifact, analysis config, and s
 | Formal element | Sheaft v1 implementation | Evidence | Boundary |
 | --- | --- | --- | --- |
 | `G=(V,E,tau)` | Bering services become `V`; Bering dependencies become `E`; edge type `tau` is represented by `kind`, `blocking`, and optional operation-aware `identity`. | `io.mb3r.bering.model@1.3.0`, `io.mb3r.bering.snapshot@1.3.0`, [examples/outputs/model-v1.3.0.sample.json](../examples/outputs/model-v1.3.0.sample.json), [examples/outputs/snapshot-v1.3.0.sample.json](../examples/outputs/snapshot-v1.3.0.sample.json) | Sheaft consumes topology; discovery ownership remains upstream in Bering. |
-| `R` | Service `replicas` and `metadata.placements[].replicas` define the replication map. `independent_replica` samples replicas or placement buckets; a service is live while at least one sampled replica bucket survives. | [docs/methodology.md](methodology.md), [configs/analysis.v1.1.example.yaml](../configs/analysis.v1.1.example.yaml) | Placement metadata is used when present; otherwise Sheaft falls back to coarse service replicas. |
+| `R` | Service `replicas` and `metadata.placements[].replicas` define the replication map. `independent_replica` samples replicas or placement buckets independently. `fixed_k_replica_slots` samples a fixed number of replica slots for experiment reproduction. A service is live while at least one sampled replica bucket survives. | [docs/methodology.md](methodology.md), [configs/analysis.example.yaml](../configs/analysis.example.yaml) | Placement metadata is used when present; otherwise Sheaft falls back to coarse service replicas. |
 | `P` | The v1 baseline is `P_Node * P_Edge`: node/service live events and edge live events are sampled independently before optional reviewed fault overlays. | [docs/oracle-suite.md](oracle-suite.md), `make oracle-suite` | Arbitrary non-product `P` is out of scope. Correlated failures are explicit fault overlays, not inferred probability distributions. |
 | `theta` | `analysis.reliability.node_live_probability`, `profiles[].reliability.node_live_probability`, per-service overrides, and Bering reliability evidence resolve node live probabilities. Legacy `failure_probability` maps to `1 - theta` only when explicit node reliability is absent. | [docs/configuration.md](configuration.md), [api/schema/analysis.schema.json](../api/schema/analysis.schema.json) | Sheaft does not do automatic probability calibration from telemetry. Inputs must be configured or provided as upstream evidence. |
 | `rho` | `analysis.reliability.edge_live_probability`, `profiles[].reliability.edge_live_probability`, per-edge overrides, and Bering edge reliability evidence resolve edge live probabilities. | [docs/configuration.md](configuration.md), [configs/analysis.v1.1.example.yaml](../configs/analysis.v1.1.example.yaml) | Per-edge overrides must use edge IDs present in the artifact being analyzed. |
diff --git a/internal/config/analysis.go b/internal/config/analysis.go
@@ -19,6 +19,7 @@ const (
 	SamplingModeIndependentReplica = "independent_replica"
 	SamplingModeIndependentService = "independent_service"
 	SamplingModeFixedKServiceSet   = "fixed_k_service_set"
+	SamplingModeFixedKReplicaSlots = "fixed_k_replica_slots"
 )
 
 type GateEvaluationRule string
@@ -273,10 +274,13 @@ func (c AnalysisConfig) Validate() error {
 			return fmt.Errorf("profile %q has unsupported sampling_mode %q", profile.Name, profile.SamplingMode)
 		}
 		switch profile.SamplingMode {
-		case SamplingModeIndependentReplica, SamplingModeIndependentService:
+		case SamplingModeIndependentReplica, SamplingModeIndependentService, SamplingModeFixedKReplicaSlots:
 			if profile.FailureProbability < 0 || profile.FailureProbability > 1 {
 				return fmt.Errorf("profile %q failure_probability must be in range [0,1]", profile.Name)
 			}
+			if profile.SamplingMode == SamplingModeFixedKReplicaSlots && profile.FixedKFailures < 0 {
+				return fmt.Errorf("profile %q fixed_k_failures must be >= 0", profile.Name)
+			}
 		case SamplingModeFixedKServiceSet:
 			if profile.FixedKFailures < 0 {
 				return fmt.Errorf("profile %q fixed_k_failures must be >= 0", profile.Name)
@@ -479,7 +483,7 @@ func resolveRelative(baseDir, target string) string {
 
 func isValidSamplingMode(mode string) bool {
 	switch mode {
-	case SamplingModeIndependentReplica, SamplingModeIndependentService, SamplingModeFixedKServiceSet:
+	case SamplingModeIndependentReplica, SamplingModeIndependentService, SamplingModeFixedKServiceSet, SamplingModeFixedKReplicaSlots:
 		return true
 	default:
 		return false
diff --git a/internal/config/analysis_test.go b/internal/config/analysis_test.go
@@ -116,6 +116,33 @@ gate:
 	}
 }
 
+func TestLoadAnalysis_AcceptsFixedKReplicaSlots(t *testing.T) {
+	t.Parallel()
+
+	path := filepath.Join(t.TempDir(), "analysis.yaml")
+	writeConfigFile(t, path, `
+schema_version: "1.0"
+profiles:
+  - name: experiment
+    sampling_mode: fixed_k_replica_slots
+    failure_probability: 0.30
+gate:
+  mode: report
+  default_action: report
+`)
+
+	cfg, err := LoadAnalysis(path)
+	if err != nil {
+		t.Fatalf("LoadAnalysis failed: %v", err)
+	}
+	if got := cfg.Profiles[0].SamplingMode; got != SamplingModeFixedKReplicaSlots {
+		t.Fatalf("expected fixed replica slot sampling mode, got %q", got)
+	}
+	if got := cfg.Profiles[0].FailureProbability; got != 0.30 {
+		t.Fatalf("expected failure_probability 0.30, got %f", got)
+	}
+}
+
 func writeConfigFile(t *testing.T, path string, content string) {
 	t.Helper()
 	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
diff --git a/internal/simulation/advanced.go b/internal/simulation/advanced.go
@@ -148,6 +148,10 @@ func runAdvancedProfile(ctx advancedContext, profile ProfileParams, defaultWeigh
 	if err := validateAdvancedReliability(ctx, profile); err != nil {
 		return ProfileOutput{}, err
 	}
+	profile, err := resolveDerivedFixedKProfile(profile, totalAdvancedReplicaSlots(ctx))
+	if err != nil {
+		return ProfileOutput{}, err
+	}
 	rng := rand.New(rand.NewSource(profile.Seed))
 	faultState := buildProfileFaultState(ctx, faultSpec)
 	staticByPath := make(map[string]pathStatic)
@@ -523,6 +527,30 @@ func sampleAdvancedState(ctx advancedContext, profile ProfileParams, rng *rand.R
 				state.bucketAlive[bucket.ID] = !failed
 			}
 		}
+	case config.SamplingModeFixedKReplicaSlots:
+		slotBucketIDs := advancedReplicaSlotBucketIDs(ctx)
+		if profile.FixedKFailures > len(slotBucketIDs) {
+			return sampledState{}, fmt.Errorf("fixed_k_failures %d exceeds replica slot count %d", profile.FixedKFailures, len(slotBucketIDs))
+		}
+		for _, serviceID := range ctx.serviceIDs {
+			for _, bucket := range ctx.services[serviceID].Buckets {
+				state.bucketAlive[bucket.ID] = true
+			}
+		}
+		if profile.FixedKFailures > 0 {
+			failedByBucket := make(map[string]int, len(slotBucketIDs))
+			indices := rng.Perm(len(slotBucketIDs))
+			for _, idx := range indices[:profile.FixedKFailures] {
+				failedByBucket[slotBucketIDs[idx]]++
+			}
+			for _, serviceID := range ctx.serviceIDs {
+				for _, bucket := range ctx.services[serviceID].Buckets {
+					if failedByBucket[bucket.ID] >= bucket.Replicas {
+						state.bucketAlive[bucket.ID] = false
+					}
+				}
+			}
+		}
 	default:
 		return sampledState{}, fmt.Errorf("unsupported sampling mode %q", profile.SamplingMode)
 	}
@@ -1520,6 +1548,28 @@ func normalizeBuckets(svc model.Service, record artifact.SnapshotDiscoveryServic
 	return out, nil
 }
 
+func totalAdvancedReplicaSlots(ctx advancedContext) int {
+	total := 0
+	for _, serviceID := range ctx.serviceIDs {
+		for _, bucket := range ctx.services[serviceID].Buckets {
+			total += bucket.Replicas
+		}
+	}
+	return total
+}
+
+func advancedReplicaSlotBucketIDs(ctx advancedContext) []string {
+	out := make([]string, 0, totalAdvancedReplicaSlots(ctx))
+	for _, serviceID := range ctx.serviceIDs {
+		for _, bucket := range ctx.services[serviceID].Buckets {
+			for replica := 0; replica < bucket.Replicas; replica++ {
+				out = append(out, bucket.ID)
+			}
+		}
+	}
+	return out
+}
+
 func findEdgeRecord(records map[string]artifact.SnapshotDiscoveryEdge, edgeID, from, to string, kind model.EdgeKind, blocking bool) artifact.SnapshotDiscoveryEdge {
 	if record, ok := records[edgeID]; ok {
 		return record
diff --git a/internal/simulation/advanced_test.go b/internal/simulation/advanced_test.go
@@ -157,6 +157,62 @@ func TestRunArtifactProfiles_ReplicatedTargetSaturatesAtEdgeBottleneck(t *testin
 	}
 }
 
+func TestRunArtifactProfiles_FixedKReplicaSlots(t *testing.T) {
+	t.Parallel()
+
+	loaded := artifact.Loaded{
+		Metadata: artifact.Metadata{
+			Contract: modelcontract.SupportedContract{
+				Name:    modelcontract.BeringModelV130Name,
+				Version: modelcontract.BeringModelV130Version,
+				URI:     modelcontract.BeringModelV130URI,
+				Digest:  modelcontract.BeringModelV130Digest,
+				Kind:    modelcontract.KindModel,
+			},
+		},
+		Model: model.ResilienceModel{
+			Services: []model.Service{
+				{ID: "frontend", Name: "frontend", Replicas: 2},
+			},
+			Endpoints: []model.Endpoint{
+				{ID: "frontend:GET /health", EntryService: "frontend", SuccessPredicateRef: "frontend:GET /health"},
+			},
+			Metadata: model.Metadata{
+				SourceType:   "test",
+				SourceRef:    "fixture",
+				DiscoveredAt: "2026-07-01T00:00:00Z",
+				Confidence:   1,
+				Schema: model.Schema{
+					Name:    modelcontract.BeringModelV130Name,
+					Version: modelcontract.BeringModelV130Version,
+					URI:     modelcontract.BeringModelV130URI,
+					Digest:  modelcontract.BeringModelV130Digest,
+				},
+			},
+		},
+	}
+
+	out, err := RunArtifactProfiles(loaded, AnalysisParams{
+		Seed: 13,
+		Profiles: []ProfileParams{
+			{Name: "derived", Trials: 1000, SamplingMode: config.SamplingModeFixedKReplicaSlots, FailureProbability: 0.5},
+			{Name: "explicit", Trials: 1000, SamplingMode: config.SamplingModeFixedKReplicaSlots, FixedKFailures: 2},
+		},
+	})
+	if err != nil {
+		t.Fatalf("RunArtifactProfiles failed: %v", err)
+	}
+	if out.Profiles[0].FixedKFailures != 1 {
+		t.Fatalf("expected derived fixed_k_failures=1, got %d", out.Profiles[0].FixedKFailures)
+	}
+	if got := out.Profiles[0].EndpointAvailability["frontend:GET /health"]; got != 1 {
+		t.Fatalf("expected one failed replica slot to leave service alive, got %f", got)
+	}
+	if got := out.Profiles[1].EndpointAvailability["frontend:GET /health"]; got != 0 {
+		t.Fatalf("expected two failed replica slots to kill service, got %f", got)
+	}
+}
+
 func TestRunArtifactProfiles_EndpointSemanticsImmediateIgnoresAsyncAndEventualUsesIt(t *testing.T) {
 	t.Parallel()
 
diff --git a/internal/simulation/simulation.go b/internal/simulation/simulation.go
diff --git a/internal/simulation/simulation_test.go b/internal/simulation/simulation_test.go
diff --git a/release/v1.1.0.md b/release/v1.1.0.md
