ci: naive tracey

Author: valeratrades

.config/tracey/config.kdl

@@ -0,0 +1,12 @@
+// Protocol contract specification traceability
+// Run: `tracey matrix` to see coverage
+// Run: `tracey impact <rule>` to see what code implements a rule
+
+spec {
+    name "protocol"
+    rules_file "../../docs/spec/_rules.json"
+    include "discretionary_engine/**/*.rs"
+    include "discretionary_engine_*/**/*.rs"
+    exclude "**/target/**"
+    exclude "**/libs/**"
+}

discretionary_engine/src/exchange_apis/mod.rs

@@ -1,4 +1,4 @@
-//! Individual exchange APIs expose methods and frameworks for interacting with their respective exchanges. At this level we have [hub.rs] and [all_exchanges.rs] which interpret the information passed up by the individual exchanges in the manner necessary for the task. [all_exchanges.rs] exposes information for Protocols and Positions, [hub.rs] uses it to construct the optimal execution strategy.
+//! Individual exchange APIs expose methods and frameworks for interacting with their respective exchanges. At this level we have `hub` and `exchanges` which interpret the information passed up by the individual exchanges in the manner necessary for the task. `exchanges` exposes information for Protocols and Positions, `hub` uses it to construct the optimal execution strategy.
 
 pub mod binance;
 pub mod exchanges;

discretionary_engine/src/positions.rs

@@ -318,6 +318,7 @@ fn recalculate_protocol_orders(
 		}
 	}
 
+	// [impl protocol.orders.market-first]
 	/// NB: Market-like orders MUST be ran first
 	fn update_order_selection(extendable: &mut Vec<ConceptualOrder<ProtocolOrderId>>, incoming: &[ConceptualOrder<ProtocolOrderId>], left_to_target: &mut f64) {
 		for order in incoming {

discretionary_engine/src/protocols/mod.rs

@@ -199,7 +199,10 @@ pub struct RecalculateOrdersPerOrderInfo {
 
 /// Wrapper around Orders, which allows for updating the target after a partial fill, without making a new request to the protocol.
 ///
-/// NB: the protocol itself must internally uphold the equality of ids attached to orders to corresponding fields of ProtocolOrders, as well as to ensure that all possible orders the protocol can ether request are initialized in every ProtocolOrders instance it outputs.
+/// # Contract
+/// - [impl protocol.orders.id-stability]: Protocol must maintain stable order IDs - ordinal indices must remain constant
+/// - [impl protocol.orders.id-match]: ProtocolOrderId must match protocol signature and ordinal position
+/// - [impl protocol.orders.all-slots-initialized]: All possible orders must have slots, inactive ones as None
 #[derive(Clone, Debug, Default)]
 pub struct ProtocolOrders {
 	pub protocol_id: String,
@@ -208,6 +211,7 @@ pub struct ProtocolOrders {
 impl ProtocolOrders {
 	#[instrument(skip(orders))]
 	pub fn new(protocol_id: String, orders: Vec<Option<ConceptualOrderPercents>>) -> Self {
+		// [verify protocol.orders.all-slots-initialized]
 		assert_ne!(
 			orders.len(),
 			0,

docs/spec/protocol.md

@@ -0,0 +1,21 @@
+# Protocol System Specification
+
+## Order Identity
+
+r[protocol.orders.id-stability]
+
+A protocol MUST maintain stable order IDs across its lifetime. The ordinal index in `ProtocolOrders.__orders` for a given logical order MUST remain constant across all updates.
+
+r[protocol.orders.id-match]
+
+The `ProtocolOrderId` attached to each order MUST match the protocol's signature and the order's ordinal position in the orders vector.
+
+r[protocol.orders.all-slots-initialized]
+
+A protocol MUST always send a `Vec<Option<ConceptualOrderPercents>>` with slots for ALL possible orders it may ever request. Orders not currently active MUST be represented as `None`, not omitted.
+
+## Order Processing
+
+r[protocol.orders.market-first]
+
+When processing orders from protocols, market-like orders MUST be executed before other order types.

flake.nix

@@ -42,6 +42,20 @@
           };
         };
         readme = v-utils.readme-fw { inherit pkgs pname; lastSupportedVersion = "nightly-1.92"; rootDir = ./.; licenses = [{ name = "Blue Oak 1.0.0"; outPath = "LICENSE"; }]; badges = [ "msrv" "crates_io" "docs_rs" "loc" "ci" ]; };
+
+        tracey = pkgs.rustPlatform.buildRustPackage {
+          pname = "tracey";
+          version = "1.0.0";
+          src = pkgs.fetchFromGitHub {
+            owner = "bearcove";
+            repo = "tracey";
+            rev = "71cfc9d4115612467b857c868a90cc6d90ed79f7";
+            hash = "sha256-maVPj9/PZzZDEmtMjemeuOCctDrU3JXaBNDwjFTRpks=";
+          };
+          cargoHash = "sha256-pk9Ky+/5P88zAbSJKbUwyvLNFIlHJzwqQCEQrorjlk0=";
+          cargoBuildFlags = [ "-p" "tracey" ];
+          doCheck = false;
+        };
       in
       {
         packages =
@@ -91,6 +105,7 @@
             openssl
             pkg-config
             rust
+            tracey
           ] ++ pre-commit-check.enabledPackages ++ github.enabledPackages;
         };
       }