feat: implement v1 stochastic connectivity analysis

Author: a-a-k

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- 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 the published Bering `v0.3.4` release/package in `compatibility-manifest.json`
 - refreshed compatibility docs and README badges to distinguish Bering app-package sync from unchanged `1.0.0` / `1.1.0` schema contract pins
 

Makefile

@@ -31,8 +31,9 @@ endif
 DIST_DIR ?= dist
 PLATFORMS ?= linux/amd64,linux/arm64
 BENCHMARK_OUT_DIR ?= .tmp/benchmark-slice
+ORACLE_OUT_DIR ?= .tmp/oracle-suite
 
-.PHONY: help build test lint smoke-examples benchmark-slice docker-build docker-run-sample sample compatibility-manifest validate-compatibility-manifest validate-chart default-config-pack release-tools release-build image-dry-run image-local chart-package chart-publish-local release-manifest validate-release-manifest validate-release-assets release-dry-run release-local clean clean-dist
+.PHONY: help build test lint smoke-examples benchmark-slice oracle-suite docker-build docker-run-sample sample compatibility-manifest validate-compatibility-manifest validate-v1-release-docs validate-chart default-config-pack release-tools release-build image-dry-run image-local chart-package chart-publish-local release-manifest validate-release-manifest validate-release-assets release-dry-run release-local clean clean-dist
 
 ifeq ($(OS),Windows_NT)
 define MKDIR_P
@@ -59,9 +60,11 @@ help:
 	@echo "  lint                       Run go vet"
 	@echo "  smoke-examples             Build the CLI and smoke checked-in examples"
 	@echo "  benchmark-slice            Run the fixed Sheaft-on-Bering benchmark slice"
+	@echo "  oracle-suite               Run synthetic stochastic-connectivity oracle suite"
 	@echo "  docker-build               Build the local container image"
 	@echo "  docker-run-sample          Run sample pipeline in the container image"
 	@echo "  compatibility-manifest     Generate compatibility-manifest.json from strict contract pins"
+	@echo "  validate-v1-release-docs   Validate v1 docs/schema/example consistency"
 	@echo "  chart-package              Lint and package charts/sheaft into dist/charts"
 	@echo "  release-build              Produce binaries, archives, checksums, SBOM, and source archive with GoReleaser"
 	@echo "  release-manifest           Generate release-manifest.json from dist metadata"
@@ -90,6 +93,9 @@ endif
 benchmark-slice:
 	go run ./cmd/releasectl benchmark-slice --manifest benchmarks/fixed-slice/manifest.json --out-dir $(BENCHMARK_OUT_DIR)
 
+oracle-suite:
+	go run ./cmd/releasectl oracle-suite --out-dir $(ORACLE_OUT_DIR)
+
 docker-build:
 	docker build -f build/Dockerfile -t $(IMAGE) .
 
@@ -105,6 +111,9 @@ compatibility-manifest:
 validate-compatibility-manifest:
 	go run ./cmd/releasectl validate-compatibility-manifest --manifest compatibility-manifest.json
 
+validate-v1-release-docs:
+	go run ./cmd/releasectl validate-v1-release-docs --root .
+
 validate-chart:
 	go run ./cmd/releasectl validate-chart --chart-dir charts/sheaft
 
@@ -159,9 +168,9 @@ release-manifest:
 validate-release-manifest:
 	go run ./cmd/releasectl validate-release-manifest --manifest release-manifest.json
 
-validate-release-assets: validate-compatibility-manifest validate-chart validate-release-manifest
+validate-release-assets: validate-compatibility-manifest validate-v1-release-docs validate-chart validate-release-manifest
 
-release-dry-run: compatibility-manifest test smoke-examples benchmark-slice release-build default-config-pack image-dry-run chart-package release-manifest validate-release-assets
+release-dry-run: compatibility-manifest validate-v1-release-docs test smoke-examples oracle-suite benchmark-slice release-build default-config-pack image-dry-run chart-package release-manifest validate-release-assets
 
 release-local: compatibility-manifest test smoke-examples release-build
 ifeq ($(OS),Windows_NT)

README.md

@@ -66,6 +66,8 @@ Unknown or mismatched contracts are rejected. There is no silent fallback for un
 
 The current `main` line has also been app-level synced against the published Bering `v0.3.4` release/package. That sync does not change the accepted Bering schema contract pins.
 
+The planned v1 major release claim is documented in [docs/v1-major-semantics.md](docs/v1-major-semantics.md): product-baseline `P_Node * P_Edge` stochastic connectivity over Bering topology `G`, replication map `R`, and endpoint predicates `Phi`, with explicit boundaries for what remains future work.
+
 ## Installation
 
 Preferred path for the current technical preview release:
@@ -186,7 +188,7 @@ Sheaft is intentionally downstream of Bering artifacts and schemas.
 ## Known limitations
 
 - `1.1.0` analysis is only as rich as the artifact metadata. Missing retry, timeout, latency, placement, or shared-resource metadata is reported as unavailable rather than guessed.
-- Legacy explicit predicates remain service-based even when `1.1.0` edge metadata is present. Edge faults and partial degradations affect journey-based analysis and diagnostics, not old explicit predicate semantics.
+- Legacy explicit predicates remain service-based even when `1.1.0` edge metadata is present. Edge faults and partial degradations affect journey-based analysis, diagnostics, and explicit `edge_aware` predicates, not old service predicate semantics.
 - This release does not introduce or stabilize an upstream discovery pipeline. Discovery remains upstream; the local `discover` helper is experimental only.
 - `serve` and its watch loop are suitable for technical-preview evaluation, not yet for a stable long-term operational contract.
 - The richer analysis surface is available, but its configuration ergonomics and operational conventions may still change in later `0.x` releases.
@@ -202,6 +204,7 @@ make build
 make test
 make lint
 make smoke-examples
+make oracle-suite
 make benchmark-slice
 ```
 
@@ -218,12 +221,14 @@ go vet ./...
 - [Install](docs/install.md)
 - [Compatibility](docs/compatibility.md)
 - [Compatibility Matrix](docs/compatibility-matrix.md)
+- [V1 Major Semantics](docs/v1-major-semantics.md)
 - [Release Assets](docs/release-assets.md)
 - [Architecture](docs/architecture.md)
 - [Methodology](docs/methodology.md)
 - [Configuration and Schemas](docs/configuration.md)
 - [CI Gate](docs/ci-gate.md)
 - [Fixed Benchmark Slice](docs/benchmark-slice.md)
+- [Synthetic Oracle Suite](docs/oracle-suite.md)
 - [Consumer Semantics v1](docs/consumer-semantics-v1.md)
 - [Consumer Semantics v2](docs/consumer-semantics-v2.md)
 - [Versioning](VERSIONING.md)

RELEASING.md

@@ -57,6 +57,10 @@ Dry-run validation:
 make release-dry-run APP_VERSION=0.0.0-dev
 ```
 
+For the v1 major line, dry-run validation also includes `validate-v1-release-docs`. That check keeps the v1 semantics documentation, schema pins, compatibility matrix, and checked-in examples aligned.
+
+V1 release notes must link to [docs/v1-major-semantics.md](docs/v1-major-semantics.md) and must avoid claims about automatic probability calibration, arbitrary non-product `P`, live chaos execution, or rich temporal workflow models unless those features have separate shipped evidence.
+
 `release-dry-run` includes the checked-in example smoke path. You can still run it separately when you only want to validate the first-run surface:
 
 ```bash

api/schema/analysis.schema.json

@@ -33,6 +33,9 @@
       "minimum": 0,
       "maximum": 1
     },
+    "reliability": {
+      "$ref": "#/$defs/reliability"
+    },
     "fixed_k_failures": {
       "type": "integer",
       "minimum": 0
@@ -96,6 +99,9 @@
             "minimum": 0,
             "maximum": 1
           },
+          "reliability": {
+            "$ref": "#/$defs/reliability"
+          },
           "fixed_k_failures": {
             "type": "integer",
             "minimum": 0
@@ -176,5 +182,38 @@
         }
       }
     }
+  },
+  "$defs": {
+    "reliability": {
+      "type": "object",
+      "properties": {
+        "node_live_probability": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "edge_live_probability": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "services": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          }
+        },
+        "edges": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          }
+        }
+      }
+    }
   }
 }

api/schema/model.v1.1.0.schema.json

@@ -68,6 +68,25 @@
         }
       }
     },
+    "edgeIdentity": {
+      "type": "object",
+      "properties": {
+        "protocol": { "type": "string" },
+        "operation": { "type": "string" },
+        "route": { "type": "string" },
+        "topic": { "type": "string" },
+        "span_kind": { "type": "string" }
+      }
+    },
+    "reliabilityEvidence": {
+      "type": "object",
+      "required": ["live_probability"],
+      "properties": {
+        "live_probability": { "type": "number", "minimum": 0, "maximum": 1 },
+        "source": { "type": "string" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
     "placement": {
       "type": "object",
       "required": ["replicas"],
@@ -76,7 +95,8 @@
         "labels": {
           "type": "object",
           "additionalProperties": { "type": "string" }
-        }
+        },
+        "reliability": { "$ref": "#/$defs/reliabilityEvidence" }
       }
     },
     "serviceMetadata": {
@@ -85,6 +105,7 @@
         {
           "type": "object",
           "properties": {
+            "reliability": { "$ref": "#/$defs/reliabilityEvidence" },
             "failure_eligible": { "type": "boolean" },
             "placements": {
               "type": "array",
@@ -104,18 +125,44 @@
         {
           "type": "object",
           "properties": {
-            "weight": { "type": "number", "minimum": 0 }
+            "weight": { "type": "number", "minimum": 0 },
+            "reliability": { "$ref": "#/$defs/reliabilityEvidence" }
           }
         }
       ]
     },
+    "endpointSemantics": {
+      "type": "object",
+      "properties": {
+        "predicate_mode": {
+          "type": "string",
+          "enum": ["immediate_response", "eventual_completion", "external_predicate"]
+        },
+        "mandatory_targets": {
+          "type": "array",
+          "items": { "type": "string" },
+          "uniqueItems": true
+        },
+        "dependency_modes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["sync", "async"]
+          },
+          "uniqueItems": true
+        },
+        "source": { "type": "string" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
     "endpointMetadata": {
       "allOf": [
         { "$ref": "#/$defs/commonMetadata" },
         {
           "type": "object",
           "properties": {
-            "weight": { "type": "number", "minimum": 0 }
+            "weight": { "type": "number", "minimum": 0 },
+            "semantics": { "$ref": "#/$defs/endpointSemantics" }
           }
         }
       ]
@@ -209,6 +256,7 @@
           "enum": ["sync", "async"]
         },
         "blocking": { "type": "boolean" },
+        "identity": { "$ref": "#/$defs/edgeIdentity" },
         "metadata": { "$ref": "#/$defs/edgeMetadata" },
         "resilience": { "$ref": "#/$defs/resiliencePolicy" },
         "observed": { "$ref": "#/$defs/observedEdge" },

api/schema/oracle-report.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/MB3R-Lab/Sheaft/api/schema/oracle-report.schema.json",
+  "title": "SheaftOracleSuiteReport",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "suite_name",
+    "status",
+    "generated_at",
+    "outputs",
+    "cases"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string"
+    },
+    "suite_name": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pass", "fail"]
+    },
+    "generated_at": {
+      "type": "string"
+    },
+    "outputs": {
+      "type": "object",
+      "required": ["report", "summary"],
+      "properties": {
+        "report": { "type": "string" },
+        "summary": { "type": "string" }
+      }
+    },
+    "cases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "description", "status", "trials", "checks"],
+        "properties": {
+          "id": { "type": "string" },
+          "description": { "type": "string" },
+          "status": {
+            "type": "string",
+            "enum": ["pass", "fail"]
+          },
+          "trials": { "type": "integer" },
+          "error": { "type": "string" },
+          "checks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["id", "status", "expected", "actual", "tolerance", "message"],
+              "properties": {
+                "id": { "type": "string" },
+                "status": {
+                  "type": "string",
+                  "enum": ["pass", "fail"]
+                },
+                "expected": { "type": "number" },
+                "actual": { "type": "number" },
+                "tolerance": { "type": "number" },
+                "message": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}